Bellacosa Mainframe apresenta o Swagger

☕ Um Café no Bellacosa Mainframe

📚 EINA TULLE E O GRIMÓRIO QUE ENSINOU O COBOL A FALAR REST

Swagger, OpenAPI, REST, HTTP, JSON, YAML, APIs, contratos, Swagger UI, autenticação, OAuth, JWT, RACF, CICS, IMS, Db2, VSAM, z/OS Connect, CI/CD, observabilidade — e o dia em que um programador COBOL descobriu que `200 OK` não significava que a aventura havia terminado.

Sob a tutela de Eina Tulle, de Is It Wrong to Try to Pick Up Girls in a Dungeon?

🎬 PRÓLOGO — BEM-VINDO À GUILDA, AVENTUREIRO

Imagine um jovem programador COBOL chegando para seu primeiro dia em uma grande empresa.

Ele conhece algumas coisas:

IDENTIFICATION DIVISION.
PROGRAM-ID. CONSULTA.

DATA DIVISION.
WORKING-STORAGE SECTION.

01 WS-CLIENTE.
   05 WS-ID       PIC 9(09).
   05 WS-NOME     PIC X(40).

JCL ele está começando a entender.

Já ouviu falar de CICS.

Db2 ainda parece uma dungeon particularmente perigosa.

E então alguém aparece e diz:

— Precisamos criar uma API REST usando OpenAPI.

Nosso aventureiro olha para a tela como Bell Cranel provavelmente olharia para uma criatura vários níveis acima do seu.

API? REST? Swagger? OpenAPI? JSON?

É nesse momento que Eina Tulle empurra seus óculos, abre uma enorme pilha de documentos sobre a mesa da Guilda e responde:

— Antes de entrar na Dungeon, você precisa conhecer o mapa.

E talvez essa seja a melhor definição inicial de OpenAPI para um programador COBOL.

OpenAPI é parte do mapa.

Não é o monstro.

Não é a espada.

Não é o aventureiro.

É uma descrição formal de como encontrar e utilizar aquilo que existe do outro lado da porta.

E essa porta pode terminar justamente em um programa COBOL.

📜 CAPÍTULO 1 — QUANDO NASCEU O SWAGGER?

Nossa história começa muito depois do nascimento do COBOL.

COBOL surgiu em 1959.

CICS apareceu no final da década de 1960.

Db2 chegou comercialmente na década de 1980.

Swagger é praticamente uma criança perto deles.

A especificação Swagger foi criada na Wordnik em 2010 e publicada como projeto open source no ano seguinte. Em 2015, os direitos do projeto foram adquiridos pela SmartBear; naquele mesmo ano, a especificação foi doada para a recém-formada OpenAPI Initiative, sob a Linux Foundation. O Swagger 2.0 tornou-se a base do que passou a ser chamado de OpenAPI Specification. (OpenAPI Initiative)

Portanto:

1959       COBOL
  │
1969       CICS
  │
1980s      Db2
  │
2010       Swagger nasce
  │
2011       projeto/spec é publicado como open source
  │
2015       OpenAPI Initiative
  │
2017       OpenAPI 3.0
  │
2025       OpenAPI 3.2

Em setembro de 2025 foi publicada a especificação OpenAPI 3.2.0. (OpenAPI Initiative Publications)

Curiosamente, enquanto escrevemos em 2026, a página oficial de versões já lista também a 3.2.1. (OpenAPI Initiative Publications)

Mas aqui existe uma regra importantíssima para quem trabalha com mainframe:

A versão mais recente de um padrão não significa automaticamente a versão suportada por cada produto da sua arquitetura.

O IBM z/OS Connect, por exemplo, documenta seus próprios níveis suportados de OpenAPI. Portanto, consulte a matriz do produto antes de simplesmente colocar a versão mais nova no projeto.

Eina escreveria isso no topo da ficha do aventureiro:

Conheça a Dungeon antes de comprar a espada.

🧩 CAPÍTULO 2 — SWAGGER NÃO É OPENAPI

Esta é provavelmente a confusão mais comum.

Durante muito tempo Swagger era tanto o nome da especificação quanto do ecossistema.

Depois da criação da OpenAPI Initiative, houve uma separação conceitual.

Hoje podemos pensar:

OPENAPI
     ↓
ESPECIFICAÇÃO / CONTRATO

SWAGGER
     ↓
FERRAMENTAS / ECOSSISTEMA

A OpenAPI Specification é uma descrição padronizada e independente de linguagem para APIs HTTP. Ela permite que pessoas e programas descubram as capacidades de um serviço sem precisar examinar seu código-fonte. (OpenAPI Initiative Publications)

Já no universo Swagger encontramos ferramentas para trabalhar com esse contrato.

Por exemplo:

Swagger UI
Swagger Editor
Swagger Codegen

Então grave:

OpenAPI descreve. Swagger ajuda você a trabalhar com essa descrição.

Não diga simplesmente:

“Swagger é uma API.”

Não é.

📖 CAPÍTULO 3 — OPENAPI É O COPYBOOK DA FRONTEIRA?

Eina provavelmente faria uma analogia para nosso aprendiz COBOL.

Considere:

01 CLIENTE-REQUEST.
   05 CLIENTE-ID       PIC 9(09).

01 CLIENTE-RESPONSE.
   05 CLIENTE-NOME     PIC X(40).
   05 CLIENTE-STATUS   PIC X(01).
   05 CLIENTE-LIMITE   PIC S9(9)V99 COMP-3.

Um programador COBOL imediatamente reconhece que existe uma estrutura.

Agora observe uma representação externa:

Cliente:
  type: object
  properties:
    id:
      type: integer
    nome:
      type: string
    status:
      type: string
    limite:
      type: number

A semelhança conceitual ajuda.

Mas cuidado.

OpenAPI não é literalmente um COPYBOOK moderno.

OpenAPI consegue descrever muito mais sobre a interface HTTP:

URL
paths
operações
parâmetros
headers
request
response
schemas
autenticação
status codes

Podemos dizer didaticamente:

COPYBOOK
   ↓
estrutura utilizada pelo programa

OPENAPI
   ↓
contrato da interface HTTP

O COPYBOOK pode dizer como o COBOL enxerga determinado dado.

OpenAPI pode dizer como o mundo exterior conversa com o serviço.

🌐 CAPÍTULO 4 — A PORTA DA DUNGEON CHAMA-SE ENDPOINT

Suponha:

GET /api/clientes/101?page=2

Temos diferentes componentes:

GET                 HTTP METHOD

/api/clientes       PATH

101                 PATH PARAMETER

page=2              QUERY PARAMETER

O path parameter normalmente participa da identificação do recurso.

Exemplo:

/clientes/101
/clientes/102
/clientes/103

Já query parameters frequentemente aparecem em filtros, paginação, ordenação etc.:

/clientes?page=2

/clientes?cidade=Itatiba

/clientes?status=ativo&sort=nome

Para quem veio do COBOL, não há magia nisso.

Estamos simplesmente recebendo dados através de outra interface.

🏰 CAPÍTULO 5 — MAS COMO ISSO CHEGA AO MAINFRAME?

Agora entramos na parte divertida.

Imagine:

MOBILE
   │
   │ HTTPS / JSON
   ▼
API GATEWAY
   │
   ▼
z/OS CONNECT
   │
   ▼
CICS
   │
   ▼
COBOL
   │
   ├────────► Db2
   │
   └────────► VSAM

O programa COBOL não precisa transformar-se magicamente em JavaScript.

O IBM z/OS Connect pode atuar como uma camada entre APIs REST e recursos z/OS. A documentação da IBM descreve API providers capazes de transformar requisições REST em chamadas aos subsistemas z/OS e converter dados entre JSON e estruturas nativas consumíveis por COBOL, PL/I e C. (IBM)

Isso é extraordinariamente importante.

Externamente alguém manda:

{
  "clienteId": 101
}

Internamente podemos terminar com algo semelhante a:

01 CLIENTE-REQUEST.
   05 CLIENTE-ID PIC 9(09).

A interface moderna não precisa destruir o legado.

Ela pode encapsulá-lo.

🧙 CAPÍTULO 6 — O GRIMÓRIO OPENAPI

Vamos imaginar uma API:

GET /clientes/{id}

Podemos ter uma descrição OpenAPI simplificada:

openapi: 3.0.3

info:
  title: Cliente API
  version: 1.0.0

paths:
  /clientes/{id}:
    get:
      summary: Consulta cliente
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Cliente encontrado
        '404':
          description: Cliente não encontrado

Eina apontaria para isso e perguntaria:

— Onde está o COBOL?

Não está.

E esse é justamente o ponto.

O consumidor não precisa saber se atrás da API temos:

COBOL
Java
Python
CICS
IMS
Db2
VSAM
um microsserviço
ou três kobolds digitando cartões perfurados.

Ele conhece o contrato.

Isso é desacoplamento.

🖥️ CAPÍTULO 7 — SWAGGER UI É O QUADRO DE MISSÕES DA GUILDA

Agora pegamos aquele contrato e apresentamos através de uma interface.

Entra o Swagger UI.

O desenvolvedor consegue explorar coisas como:

GET /clientes/{id}

POST /clientes

PUT /clientes/{id}

DELETE /clientes/{id}

Ele pode encontrar o endpoint, observar parâmetros, analisar schemas e, quando habilitado, executar chamadas diretamente.

O fluxo apresentado nas imagens é muito didático:

OPEN SWAGGER UI
       ↓
FIND ENDPOINT
       ↓
TRY IT OUT
       ↓
ENTER PARAMETERS
       ↓
EXECUTE
       ↓
INSPECT RESPONSE
       ↓
VALIDATE

Excelente para exploração.

Mas existe uma armadilha.

Swagger UI não substitui uma estratégia completa de QA.

💚 CAPÍTULO 8 — O TERRÍVEL MONSTRO VERDE: `200 OK`

Nosso aventureiro executa:

GET /clientes/101

Swagger fica feliz:

200 OK

Ele comemora.

Eina bate o livro na mesa.

— Ainda não.

Porque 200 OK diz algo sobre o resultado da requisição HTTP.

Não prova automaticamente que a regra de negócio está correta.

Imagine:

{
  "cliente": 101,
  "saldo": 1000000.00
}

O saldo real era:

1000.00

Tecnicamente:

HTTP       OK
JSON       OK
SCHEMA     OK
NEGÓCIO    ERRADO

Isso deveria soar familiar para qualquer mainframer.

É o equivalente a:

MAXCC=0000

e descobrir depois que o arquivo de saída continha valores incorretos.

RC=0 não é sinônimo de negócio correto.

HTTP 200 também não.

🧪 CAPÍTULO 9 — O QA PRECISA DESCER MAIS ANDARES

Teste pelo menos:

status HTTP
response body
headers
campos obrigatórios
tipos
schema
valores-limite
dados inválidos
autenticação
autorização
timeout
concorrência
idempotência
rollback
indisponibilidade do backend
performance

Suponha:

POST /pagamentos

Cliente envia:

{
   "conta": "12345",
   "valor": 100
}

O backend processa.

Mas ocorre timeout antes de o cliente receber a resposta.

Ele tenta novamente.

Se não houver desenho adequado:

REQUEST 1 → DEBITA R$100

TIMEOUT

REQUEST 2 → DEBITA R$100

Swagger pode estar perfeitamente configurado.

OpenAPI pode estar impecável.

E você acabou de cobrar o cliente duas vezes.

Bem-vindo ao andar onde moram os monstros de verdade.

⚛️ CAPÍTULO 10 — REST NÃO MATOU ACID

Por trás de:

POST /transferencias

pode existir:

UPDATE CONTA A
      ↓
UPDATE CONTA B
      ↓
COMMIT

Se algo falhar:

ROLLBACK

Portanto:

REST
 ↓
JSON
 ↓
z/OS Connect
 ↓
CICS
 ↓
COBOL
 ↓
Db2
 ↓
LOCKS
 ↓
LOG
 ↓
COMMIT / ROLLBACK

A modernização da interface não aboliu cinquenta anos de engenharia transacional.

Isso é uma das coisas mais importantes para um iniciante entender.

API é a porta da Dungeon.

Não é a Dungeon inteira.

🔐 CAPÍTULO 11 — “QUEM É VOCÊ?” E “O QUE VOCÊ PODE FAZER?”

Outra imagem traz uma distinção excelente:

AUTHENTICATION
Quem é você?

AUTHORIZATION
O que você pode fazer?

Podemos encontrar mecanismos como:

Basic Authentication
API Key
Bearer Token
JWT
OAuth 2.0

Agora transporte isso para IBM Z:

APP
 │
 ▼
OAuth / OIDC
 │
 ▼
TOKEN
 │
 ▼
API GATEWAY
 │
 ▼
z/OS Connect
 │
 ▼
SAF / RACF
 │
 ▼
CICS
 │
 ▼
COBOL

Surge uma pergunta arquitetural fundamental:

Qual identidade chega ao recurso protegido?

Porque autenticar alguém na primeira porta não significa automaticamente permitir qualquer operação atrás dela.

É justamente daí que nasce a distinção didática entre:

401
problema de autenticação/credenciais

403
identidade reconhecida,
mas acesso não permitido

A própria oferta atual do z/OS Connect destaca autorização granular por operação para serviços de negócio. (IBM)

🚨 CAPÍTULO 12 — NÃO MANDE `SQLCODE -911` PARA O CLIENTE

Imagine:

EXEC SQL
   SELECT SALDO
     INTO :WS-SALDO
     FROM CONTA
    WHERE ID = :WS-ID
END-EXEC

Alguma condição ocorre no Db2.

Você não deveria transformar automaticamente sua implementação interna em contrato público:

{
   "sqlcode": -911
}

Muito menos:

{
   "abend": "ASRA",
   "program": "XPTO1234"
}

Você está vazando detalhes da implementação.

O ideal é existir um mapeamento coerente entre erro interno e contrato externo.

Por exemplo:

Db2: registro inexistente
        ↓
regra da aplicação
        ↓
HTTP 404

Resposta:

{
   "code": "ACCOUNT_NOT_FOUND",
   "message": "Conta não encontrada"
}

Internamente você preserva informações suficientes para diagnóstico:

timestamp
transaction ID
correlation ID
program
CICS transaction
SQLCODE
trace
logs
SMF

O usuário recebe aquilo que precisa.

Operações recebe aquilo que precisa.

Segurança agradece.

🏗️ CAPÍTULO 13 — API-FIRST: DESENHE A MISSÃO ANTES DE ENTRAR NA DUNGEON

Aqui encontramos uma transformação particularmente interessante para equipes mainframe.

Tradicionalmente poderíamos imaginar:

COBOL
 ↓
interface
 ↓
documentação

API-first inverte parte desse raciocínio.

Primeiro definimos:

CONTRATO
 ↓
IMPLEMENTAÇÃO

Imagine:

POST /transferencias

Request:

{
   "origem": "123456",
   "destino": "987654",
   "valor": 250.00
}

Response:

{
   "transacao": "TRX829173",
   "status": "EFETIVADA"
}

Agora várias equipes podem trabalhar sobre o mesmo contrato:

           OpenAPI
              │
    ┌─────────┼──────────┐
    │         │          │
 Mobile      QA       Mainframe
    │         │          │
    ▼         ▼          ▼
 cliente    testes    implementação

E isso não é apenas teoria aplicada ao IBM Z. A IBM documenta desenvolvimento API-first no z/OS Connect usando documentos OpenAPI e ferramentas que geram artefatos de projeto e estruturas de linguagem necessárias à implementação, inclusive para aplicações CICS COBOL ou PL/I. (IBM)

A funcionalidade API-first foi introduzida no z/OS Connect 3.0.69. (IBM)

Para o COBOLzeiro, isso é enorme.

O contrato deixa de ser aquele PDF que alguém atualiza seis meses depois.

Ele passa a participar do processo de engenharia.

🔄 CAPÍTULO 14 — DO SWAGGER AO CI/CD

Agora podemos expandir o workflow apresentado nas imagens:

BUSINESS REQUIREMENT
          ↓
     API DESIGN
          ↓
   OPENAPI CONTRACT
          ↓
    CONTRACT REVIEW
          ↓
        MOCK
          ↓
   BACKEND DEVELOPMENT
          ↓
     z/OS CONNECT
          ↓
     CICS / IMS
          ↓
        COBOL
          ↓
    Db2 / VSAM
          ↓
 FUNCTIONAL TEST
          ↓
 NEGATIVE TEST
          ↓
 CONTRACT TEST
          ↓
 SECURITY TEST
          ↓
 PERFORMANCE TEST
          ↓
       CI/CD
          ↓
      DEPLOY
          ↓
    PRODUCTION

E isso destrói outro mito:

“DevOps não serve para mainframe.”

Serve.

O que muda são ferramentas, processos, controles e características da plataforma.

🔭 CAPÍTULO 15 — A AVENTURA NÃO TERMINA NO DEPLOY

Produção não é:

DEPLOY
  ↓
FIM

Produção é:

DEPLOY
  ↓
OBSERVAR
  ↓
MEDIR
  ↓
INVESTIGAR
  ↓
CORRIGIR

Por isso nosso desenho final começa a ganhar novas peças:

API
 ↓
z/OS Connect
 ↓
CICS
 ↓
COBOL
 ↓
Db2

        ↘ TELEMETRIA
             ↓
        OBSERVABILIDADE

O z/OS Connect também oferece integração com mecanismos tradicionais do z/OS, incluindo rastreamento via SMF, e a linha atual oferece suporte a OpenTelemetry para observabilidade. (IBM)

Isso cria uma combinação particularmente poderosa:

OpenAPI
   =
O QUE FOI CONTRATADO

telemetria
   =
O QUE ESTÁ ACONTECENDO

Quando ambos se encontram, você deixa de simplesmente publicar APIs e começa a operá-las profissionalmente.

🗺️ CAPÍTULO 16 — O MAPA COMPLETO DA DUNGEON

Depois da aula de Eina, nosso jovem COBOLzeiro finalmente consegue desenhar:

                    CONSUMIDORES
                         │
               Web / Mobile / Cloud
                         │
                         ▼
                    HTTPS / REST
                         │
                         ▼
                 ┌───────────────┐
                 │ API CONTRACT  │
                 │    OpenAPI    │
                 └───────┬───────┘
                         │
                 Swagger UI
                         │
                         ▼
                    API GATEWAY
                         │
                   OAuth / JWT
                         │
                         ▼
                  z/OS CONNECT
                         │
           ┌─────────────┼─────────────┐
           │             │             │
           ▼             ▼             ▼
         CICS           IMS           Db2
           │             │
           ▼             ▼
         COBOL         COBOL
           │             │
           └──────┬──────┘
                  │
          ┌───────┼────────┐
          ▼       ▼        ▼
         Db2     VSAM     IMS DB
          │
          ▼
    COMMIT / ROLLBACK
          │
          ▼
    SMF / TELEMETRIA
          │
          ▼
    OBSERVABILIDADE

Agora Swagger deixou de parecer uma tecnologia alienígena.

É apenas mais uma peça da arquitetura.

💡 CAPÍTULO 17 — DEZ CONSELHOS DE EINA PARA O COBOLZEIRO

Antes de liberar nosso aventureiro para a Dungeon, Eina deixaria algumas regras no quadro da Guilda:

Não confunda Swagger com OpenAPI. Um é o ecossistema de ferramentas; o outro é a especificação.
Não trate Swagger UI como ferramenta completa de QA. Explorar endpoints é apenas o começo.
Nunca comemore apenas porque recebeu 200 OK. Valide o negócio.
Não exponha detalhes internos desnecessários. SQLCODE, ABEND e nomes internos não precisam virar sua interface pública.
Teste erros deliberadamente. Token inválido, campo ausente, valor absurdo, backend indisponível e timeout também fazem parte da API.
Pense em idempotência. Principalmente pagamentos e operações financeiras.
Separe autenticação de autorização.
Versione e governe o contrato. Alterar uma API usada por dezenas de consumidores é muito diferente de alterar uma rotina interna isolada.
Use observabilidade desde o desenho. Não espere o primeiro incidente para perguntar como correlacionar uma requisição HTTP com o processamento z/OS.
Não tente transformar COBOL em REST. Crie uma arquitetura em que REST e COBOL façam aquilo que cada tecnologia sabe fazer bem.

🥚 EASTER EGG — A REQUISIÇÃO DAS 03:17

Algumas semanas depois, produção recebe:

03:17:00.317

Uma chamada:

POST /transferencias

Swagger dizia:

201 Created

O dashboard estava verde.

CPU normal.

z/OS saudável.

CICS ativo.

Db2 ativo.

Nenhum grande alarme.

Mesmo assim, o cliente reclamava:

“Minha transferência apareceu duas vezes.”

Nosso jovem programador quase responde:

— Mas recebemos 201!

Ele para.

Lembra da aula.

Procura o correlation ID.

Segue a requisição.

API Gateway.

z/OS Connect.

CICS.

COBOL.

Db2.

COMMIT.

Depois encontra uma segunda requisição, enviada após um timeout do consumidor.

Mesmo payload.

Mesmo valor.

Outro processamento.

E então finalmente compreende a verdadeira lição daquela primeira aventura:

Disponibilidade não garante correção. HTTP correto não garante negócio correto. E observabilidade sem contexto é apenas uma coleção muito cara de luzes verdes.

No dia seguinte ele volta à Guilda.

Eina pergunta:

— Então, aprendeu Swagger?

Ele responde:

— Não.

Ela ergue uma sobrancelha.

— Aprendi sistemas.

Agora ela sorri.

☕ EPÍLOGO — O MAINFRAME NÃO PRECISA APRENDER A SER JOVEM

Existe uma narrativa recorrente na tecnologia:

velho
versus
novo

Mainframe versus cloud.

COBOL versus Java.

CICS versus microsserviços.

Batch versus APIs.

Essa oposição frequentemente é simplista.

Uma arquitetura moderna pode perfeitamente conter:

OpenAPI
Swagger
REST
JSON
OAuth
API Gateway
z/OS Connect
RACF
CICS
COBOL
Db2
VSAM
SMF
OpenTelemetry
CI/CD

Não existe contradição nisso.

Existe integração.

A aplicação mobile não precisa conhecer PIC, COMP-3, COMMAREA ou SQLCODE.

O programa COBOL não precisa conhecer detalhes da interface gráfica do smartphone.

Entre os dois existe um contrato.

OpenAPI.

E ferramentas como Swagger ajudam pessoas e máquinas a compreender e trabalhar com esse contrato.

O IBM z/OS Connect completa uma parte importantíssima dessa ponte, expondo recursos z/OS através de APIs e realizando transformações entre o universo REST/JSON e estruturas utilizadas pelas aplicações z/OS. (IBM)

Talvez seja essa a maior lição sob a tutela de Eina Tulle.

Ela jamais mandaria um aventureiro para a Dungeon simplesmente porque ele tinha uma espada nova.

Primeiro ensinaria:

o mapa
os níveis
os monstros
as regras
as rotas
os riscos
e como voltar vivo.

Swagger UI é uma ferramenta.

OpenAPI é um contrato.

REST é um estilo arquitetural.

HTTP é um protocolo.

JSON é uma representação de dados.

OAuth pode participar da segurança.

z/OS Connect pode fazer a ponte.

CICS pode administrar a transação.

COBOL pode executar a regra de negócio.

Db2 pode preservar os dados.

RACF/SAF pode participar da proteção.

SMF e OpenTelemetry podem ajudar a contar o que aconteceu.

Nenhuma dessas peças, sozinha, é “a modernização”.

A arquitetura aparece quando sabemos como todas elas se relacionam.

E é justamente por isso que talvez a pergunta mais interessante não seja:

“Como substituir COBOL por APIs?”

Mas:

“Como fazer décadas de lógica de negócio confiável participarem de um mundo orientado a APIs sem destruir aquilo que já funciona?”

Quando nosso jovem aventureiro consegue responder isso, ele já não está apenas aprendendo Swagger.

Ele começou a compreender o verdadeiro mapa da Dungeon chamada Enterprise Computing.

E em algum lugar, às 03:17, Eina Tulle fecha o último manual da Guilda e escreve na ficha do aventureiro:

LEVEL UP: COBOL PROGRAMMER → API-AWARE MAINFRAMER.

Translate

quarta-feira, 8 de setembro de 2021