OpenAPI 3.1: documente sua API antes de construí-la

1. Por que documentar antes de codificar?

A abordagem design-first inverte a lógica tradicional de desenvolvimento. Em vez de codificar a API e depois documentá-la, você primeiro define o contrato da interface e só então implementa o código. Essa mudança de mentalidade traz benefícios concretos:

  • Contrato como fonte da verdade: a especificação OpenAPI vira o documento central que alinha frontend, backend e QA. Cada equipe sabe exatamente o que esperar dos endpoints, parâmetros e respostas antes de uma linha de código ser escrita.
  • Redução de retrabalho: inconsistências são identificadas na fase de design, não após semanas de implementação. Um erro de tipo em um campo descoberto no papel custa minutos para corrigir; descoberto em produção, custa horas de debugging e refatoração.
  • Paralelismo real: frontend pode consumir um mock server gerado da especificação enquanto o backend ainda está sendo desenvolvido. Testes de contrato podem ser escritos simultaneamente.

2. O que há de novo no OpenAPI 3.1?

A versão 3.1, lançada em fevereiro de 2021, representa a maior atualização desde a 3.0. As mudanças principais incluem:

  • Alinhamento total com JSON Schema 2020-12: agora Schema Object é literalmente um JSON Schema válido. Isso elimina ambiguidades e permite usar recursos avançados como $defs, unevaluatedProperties, e prefixItems.
  • Suporte nativo a webhooks: a especificação agora permite definir eventos assíncronos que sua API pode disparar, sem precisar recorrer a extensões proprietárias.
  • Exemplos e descrições aprimorados: o campo examples agora aceita múltiplos exemplos nomeados, e description suporta CommonMark para formatação rica.

3. Estrutura básica de um documento OpenAPI 3.1

Todo documento OpenAPI 3.1 começa com três campos obrigatórios:

openapi: 3.1.0
info:
  title: API de Catálogo de Produtos
  version: 1.0.0
  description: API para gerenciamento de produtos em uma loja virtual
paths:
  /produtos:
    get:
      summary: Lista todos os produtos
      operationId: listarProdutos
      responses:
        '200':
          description: Lista de produtos retornada com sucesso
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Produto'
components:
  schemas:
    Produto:
      type: object
      properties:
        id:
          type: integer
        nome:
          type: string
        preco:
          type: number

O campo paths define os endpoints. Cada path contém methods HTTP (get, post, put, delete, etc.) que descrevem parâmetros, request bodies e respostas. O bloco components centraliza schemas, responses e security schemes para reuso.

4. Definindo modelos de dados com JSON Schema

Com o alinhamento ao JSON Schema 2020-12, a definição de modelos ficou mais expressiva. Veja um exemplo de schema complexo com composição:

components:
  schemas:
    Endereco:
      type: object
      properties:
        rua:
          type: string
        cidade:
          type: string
        cep:
          type: string
          pattern: '^[0-9]{5}-[0-9]{3}$'
    Cliente:
      type: object
      properties:
        id:
          type: integer
        nome:
          type: string
          minLength: 2
          maxLength: 100
        email:
          type: string
          format: email
        endereco:
          $ref: '#/components/schemas/Endereco'
        tipo:
          type: string
          enum: [PF, PJ]
      required: [nome, email, tipo]
    Pedido:
      type: object
      allOf:
        - $ref: '#/components/schemas/Cliente'
        - type: object
          properties:
            itens:
              type: array
              items:
                $ref: '#/components/schemas/ItemPedido'
            total:
              type: number
              exclusiveMinimum: 0

O uso de allOf permite composição de schemas, enquanto oneOf e anyOf habilitam polimorfismo. A validação de dados fica explícita: formatos (email, date, uri), padrões regex e restrições de tamanho garantem que apenas dados válidos trafeguem.

5. Documentando autenticação e autorização

A segurança é documentada no bloco components.securitySchemes e aplicada globalmente ou por operação:

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
security:
  - BearerAuth: []
paths:
  /pedidos:
    post:
      summary: Cria um novo pedido
      security:
        - BearerAuth: [escopo:escrita]
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pedido'
      responses:
        '201':
          description: Pedido criado

Para OAuth2, a definição inclui flows (authorizationCode, implicit, clientCredentials) e escopos. Isso permite que ferramentas de geração de código criem clientes que automaticamente tratam da obtenção de tokens.

6. Ferramentas para trabalhar com OpenAPI 3.1

  • Swagger Editor (editor.swagger.io): editor online com validação em tempo real e preview interativo.
  • Stoplight Studio (stoplight.io): editor visual com suporte a design-first e colaboração em equipe.
  • Redocly (redocly.com): ferramenta de linting e validação que integra com CI/CD, garantindo que a especificação siga boas práticas.
  • OpenAPI Generator (openapi-generator.tech): gera código cliente e servidor em mais de 50 linguagens a partir da especificação.
  • Prism (stoplight.io/open-source/prism): mock server que simula respostas da API baseado na especificação, permitindo testes frontend sem backend real.

7. Boas práticas para documentação duradoura

  • Versionamento semântico da especificação: use version: 1.2.3 no campo info e mantenha changelogs. Nunca quebre contratos sem aviso prévio.
  • Documentação viva no CI/CD: integre ferramentas como Redocly CLI ou Spectral no pipeline para validar a especificação a cada commit. Publique a documentação HTML automaticamente.
  • Exemplos reais em cada operação: não deixe example vazio. Um exemplo concreto reduz o tempo de integração de horas para minutos.
  • Descrições completas: documente não apenas o que o endpoint faz, mas também erros comuns, limites de rate e dicas de uso.

A documentação design-first com OpenAPI 3.1 transforma a especificação de um artefato burocrático em uma ferramenta de produtividade. O contrato vira o blueprint que guia todo o desenvolvimento, reduz retrabalho e acelera a entrega. Invista tempo no design antes do código — sua equipe (e seus consumidores) agradecerão.

Referências