Validador de OpenAPI

A OpenAPI Specification: do Swagger ao OpenAPI 3.1

A OpenAPI Specification (OAS) e o padrao mais adotado para descrever APIs HTTP. Surgiu em 2010 como Swagger, virou padrao aberto em 2015 quando a SmartBear doou o trabalho a Linux Foundation, e hoje e mantida pela OpenAPI Initiative. Versoes em uso: Swagger 2.0 (legado, ainda comum), OpenAPI 3.0 (modular, 2017) e OpenAPI 3.1 (atual, 2021), que finalmente se alinha ao JSON Schema Draft 2020-12.

Uma spec valida e um documento YAML ou JSON que descreve completamente endpoints, metodos, parametros, request bodies, respostas, esquemas de seguranca e servidores. Dessa fonte unica voce gera documentacao interativa, stubs de servidor, SDKs de cliente, mock servers, contract tests e regras de lint.

Anatomia de um documento OpenAPI

Chaves de topo obrigatorias ou recomendadas em toda spec:

• openapi — a versao da spec (3.0.3, 3.1.0).
• info — titulo, versao, descricao, licenca e contato da API.
• servers — URLs base (producao, staging, sandbox) com variaveis opcionais.
• paths — catalogo de rotas; cada path mapeia metodos HTTP para operacoes.
• components — schemas, responses, parameters, requestBodies, securitySchemes, examples, headers reutilizaveis.
• security — aplicada globalmente ou por operacao; referencia esquemas em components.
• tags — agrupam operacoes na documentacao gerada.

openapi: 3.1.0
info:
  title: API de Usuarios
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Busca usuario por id
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/User' }
components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:    { type: string, format: uuid }
        email: { type: string, format: email }

Ferramentas: docs, editores, validadores, codegen

• Swagger UI — explorador interativo com "Try it out"; produto original do Swagger.
• Redoc — documentacao read-only em tres colunas, otima para referencias publicas.
• Stoplight Studio e Insomnia Designer — editores visuais que fazem round-trip YAML/JSON.
• swagger-parser (Node) e openapi-validator (IBM) — schema + resolucao de referencias.
• Spectral (Stoplight) — linter de OpenAPI; rulesets impoem nomenclatura, cobertura de tags, codigos de resposta.
• openapi-generator — gera SDKs de cliente e stubs de servidor em mais de 40 linguagens.
• Prism e Stoplight mock — mock servers instantaneos guiados por examples na spec.
• Postman e Insomnia — importam OpenAPI e montam collections automaticamente.

OpenAPI vs API Blueprint, gRPC, AsyncAPI

• vs API Blueprint — formato Markdown da Apiary; descontinuado na pratica depois que a OpenAPI dominou o ecossistema.
• vs gRPC + Protobuf — gRPC usa HTTP/2 binario e IDL Protobuf para trafego service-to-service; OpenAPI descreve APIs HTTP/JSON textuais voltadas a consumo publico.
• vs AsyncAPI — mesma ideia, mas para sistemas orientados a eventos (Kafka, RabbitMQ, MQTT, WebSocket). Muitos times publicam os dois.
• vs GraphQL SDL — paradigma diferente (endpoint unico, linguagem de consulta tipada). OpenAPI descreve semantica REST.

API-first e o Open Finance Brasil

API-first e o fluxo em que a spec OpenAPI vem antes do codigo, passa pelo Spectral e e revisada em pull request. Da spec aprovada nascem SDKs de cliente, stubs de servidor e mock servers; backend e frontend trabalham em paralelo sem bloquear um ao outro.

No Brasil, o setor publico adotou OpenAPI com forca. Receita Federal, Banco Central e todo o ecossistema do Open Finance Brasil (antigo Open Banking BR) publicam specs OpenAPI 3.x. A Fase 4, em producao desde 2022, padronizou as APIs por onde bancos compartilham dados de clientes e iniciam pagamentos — todo participante certificado expoe endpoints que casam exatamente com a spec oficial, validados por suites de teste automatizadas.

Boas praticas que fazem diferenca

• Use tags — Swagger UI e Redoc agrupam operacoes por tag; sem isso a documentacao vira uma lista plana.
• Inclua examples em cada request body e response — alimentam mock servers, testes de SDK e clientes.
• Declare todos os erros — 400, 401, 403, 404, 422, 429, 500; clientes se preparam para eles.
• Defina security schemes — oauth2 com flows, apiKey em header, http: bearer; referencie nas operacoes.
• Reuse schemas via $ref — tipos como Dinheiro, Endereco e Pagination merecem componente proprio.
• Lint com Spectral no CI — imponha nomenclatura, cobertura de respostas, casing e documentacao completa.

FAQ

Devo escrever Swagger 2.0 ou OpenAPI 3.x?

OpenAPI 3.x, sempre. 3.1 e preferida em projetos novos porque alinha ao JSON Schema 2020-12; 3.0 vale quando o tooling esta atrasado. Swagger 2.0 e legado.

YAML ou JSON?

YAML e mais legivel para humanos (comentarios, sem aspas); JSON e mais amigavel a geradores e CI. Maioria escreve em YAML e converte para JSON sob demanda. Os dois sao formalmente equivalentes em OpenAPI.

Da para subir mock server direto da spec?

Sim — Prism (Stoplight) e Mockoon sobem um servidor HTTP que devolve os examples e respeita os schemas, perfeito para frontend trabalhar antes do backend ficar pronto.

OpenAPI 3.1 usa JSON Schema mesmo?

Sim — 3.1 embute JSON Schema Draft 2020-12 inteiro, entao qualquer keyword (oneOf, const, $defs) e legal nos seus schemas sem traducao. Essa foi a motivacao principal do salto 3.0 -> 3.1.

E webhooks e callbacks?

OpenAPI 3.1 trouxe um objeto webhooks no topo para descrever eventos que seu servico emite; antes voce modelava em callbacks dentro de operacoes. Os dois continuam funcionando por compatibilidade.