Documentação e OpenAPI

O problema: documentação que ninguém confere

Toda API tem alguma documentação: uma página na wiki, um README, uma coleção de pedidos salva numa ferramenta. O problema é que ela é escrita uma vez e esquecida. O campo criado_em virou criado_em_utc, um parâmetro passou a ser obrigatório, o erro 404 mudou de formato, e a página continua igual.

Quem integra descobre a diferença em produção. E quem mantém a API não sabe quais clientes dependem do que, porque o que a API promete não está escrito em lugar nenhum que uma máquina consiga ler.

O que é a OpenAPI

A OpenAPI é um formato padrão, em YAML ou JSON, para descrever uma API HTTP: as rotas, os parâmetros, os corpos dos pedidos, as respostas de cada status e os erros. Um trecho:

paths:
  /pedidos/{id}:
    get:
      operationId: buscarPedido
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer, minimum: 1 }
      responses:
        "200":
          description: O pedido
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Pedido" }
        "404":
          description: Pedido não encontrado

Os esquemas dos dados usam o JSON Schema: tipos, campos obrigatórios, formatos, valores permitidos, mínimos e máximos. A versão 3.1 da OpenAPI adota o JSON Schema completo. A 3.0, ainda muito comum, usa uma variação com diferenças pequenas, como nullable: true no lugar de type: [string, "null"].

O nome antigo era Swagger, e ele ainda aparece nas ferramentas: o Swagger UI é a página interativa mais conhecida que mostra um arquivo OpenAPI.

O que sai do arquivo

O valor da OpenAPI não está na página bonita. Está em ser um arquivo que as ferramentas leem:

Duas formas de chegar ao arquivo

As duas formas têm o mesmo ponto fraco: nada garante que o arquivo e o código concordam. A diferença é só de que lado o erro aparece. Os testes abaixo medem esse ponto fraco.

A especificação gerada pelo código também erra

Escrevemos a mesma API de pedidos (criar e buscar) com o gerador de OpenAPI mais usado em cada linguagem: Fastify, FastAPI, huma (Go), Spring com springdoc e ASP.NET Core 9. Depois, rodamos o Schemathesis contra cada servidor. Ele lê a especificação publicada pelo próprio servidor, gera pedidos válidos e inválidos a partir dela e confere se as respostas batem com o que o arquivo promete.

As cinco especificações foram reprovadas em pelo menos um ponto:

O último caso é o mais grave. A especificação diz que os dois campos são obrigatórios e que o cliente precisa ser maior que zero, mas o código não confere nada disso: as anotações de validação estavam lá, e o ASP.NET Core 9 só as usa para escrever a documentação. Quem lê o arquivo confia numa regra que não existe.

O caso do springdoc é sutil e tem efeito prático. Sem campos obrigatórios no esquema, um gerador de clientes cria tipos em que todo campo pode faltar, e o código de quem integra se enche de verificações desnecessárias.

O contrato escrito à mão também erra

Em seguida, escrevemos o contrato à mão, no estilo design-first: campos obrigatórios, valores em texto para não perder centavos, inteiros limitados a 32 bits e erros no formato Problem Details (application/problem+json). Rodamos o Schemathesis com esse contrato contra os cinco servidores:

Nem todas as divergências eram culpa do código. O total "0.00" mostrou uma regra que o contrato esqueceu: um pedido não pode ter total zero. O teste de contrato confere os dois lados, e cada divergência obriga a decidir quem está certo.

Mudanças que quebram quem integra

Com o contrato num arquivo versionado, cada mudança vira um diff que uma ferramenta consegue julgar. Fizemos quatro mudanças comuns no contrato e passamos as duas versões pelo oasdiff:

O último resultado surpreende quem nunca pensou nele: acrescentar um valor ao status parece inofensivo, mas um cliente escrito com um switch sobre os três valores antigos não sabe tratar o quarto. É o mesmo cuidado do tópico de versionamento de API, agora conferido por uma máquina a cada mudança.

Por que isso importa quando a IA escreve o código

Um assistente que escreve uma API costuma gerar a documentação junto, e ela parece completa. Os problemas típicos:

• Anotações de validação que aparecem na documentação, mas não são aplicadas, como no ASP.NET Core 9.
• Respostas de erro (400, 404, 422) sem documentação, ou documentadas com o esquema de sucesso.
• Campos sem required, e clientes gerados em que tudo pode faltar.
• Dinheiro como number, e datas sem format: date-time.
• Um arquivo OpenAPI escrito uma vez e nunca conferido contra a API.
• Mudanças incompatíveis, como renomear um campo, feitas "só para padronizar", sem nenhuma verificação.

O próximo nível compara as formas de produzir e manter o contrato, e as ferramentas de cada etapa.