OpenAPI no Node.js

Atualizado em: 7 de outubro de 2026

Terminal Linux usado em desenvolvimento e administração de aplicações Node.js

OpenAPI descreve APIs HTTP de forma legível por pessoas e ferramentas. Em projetos Node.js, o documento pode gerar documentação, clientes, testes, mocks, validação e contratos entre equipes. O arquivo não substitui o código, mas reduz ambiguidades sobre rotas, parâmetros, autenticação e respostas.

Documento mínimo

openapi: 3.1.0
info:
  title: Orders API
  version: 1.0.0
servers:
  - url: https://api.example.com
paths:
  /orders/{id}:
    get:
      operationId: getOrder
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Pedido encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          $ref: '#/components/responses/NotFound'

Componentes reutilizáveis

components:
  schemas:
    Order:
      type: object
      required: [id, status, total]
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum: [pending, paid, cancelled]
        total:
          type: number
          minimum: 0
  responses:
    NotFound:
      description: Recurso não encontrado

Use componentes para erros, paginação, segurança e objetos compartilhados. Evite referências excessivamente fragmentadas.

OpenAPI 3.1 e JSON Schema

A versão 3.1 aproxima schemas do JSON Schema moderno. Declare tipos, formatos, required, enum, oneOf e restrições com precisão. Confirme suporte das ferramentas escolhidas.

Design-first ou code-first

No design-first, o contrato é revisado antes da implementação. No code-first, decorators ou schemas geram o documento. Ambos funcionam; o risco é o documento divergir do comportamento real.

operationId

Defina um identificador único e estável para cada operação. Geradores de cliente usam esse valor como nome de função. Evite mudá-lo sem considerar compatibilidade.

Parâmetros

Documente path, query, header e cookie. Declare required, limites, exemplos e formatos:

- in: query
  name: limit
  schema:
    type: integer
    minimum: 1
    maximum: 100
    default: 20

Request body

requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/CreateOrder'

Inclua Content-Types realmente aceitos. Não documente multipart se a rota não o suporta.

Erros padronizados

Problem:
  type: object
  required: [type, title, status]
  properties:
    type:
      type: string
      format: uri
    title:
      type: string
    status:
      type: integer
    detail:
      type: string
    requestId:
      type: string

Um formato consistente facilita clientes e observabilidade. Não exponha stack trace.

Autenticação Bearer

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []

Rotas públicas podem sobrescrever com security: [].

API key e OAuth

Documente o local da API key e scopes OAuth. Não coloque credenciais reais em exemplos.

Paginação

Descreva cursor, limit, links e comportamento de ordenação. Cursor deve ser tratado como string opaca pelo cliente.

Idempotência

Para operações que usam Idempotency-Key, documente header, validade, conflitos e resposta de replay.

Uploads

content:
  multipart/form-data:
    schema:
      type: object
      required: [file]
      properties:
        file:
          type: string
          format: binary

Inclua limites de tamanho, tipos permitidos e respostas de validação na descrição.

Callbacks e webhooks

OpenAPI pode documentar callbacks. Para catálogos de eventos mais complexos, considere AsyncAPI. Defina assinatura, retries e idempotência.

Servindo Swagger UI

import swaggerUi from 'swagger-ui-express';
import openapi from './openapi.json' with { type: 'json' };

app.use('/docs', swaggerUi.serve, swaggerUi.setup(openapi));

Em APIs privadas, proteja a documentação. Não inclua endpoints internos ou exemplos com dados reais.

Validação de requisições

Middlewares podem validar request e response contra o contrato. Defina política para propriedades adicionais e erros. Validação de resposta é especialmente útil em testes e staging.

Lint

Use um linter para exigir operationId, descrições, exemplos, erros e padrões de nomes. Regras personalizadas evitam contratos inconsistentes.

Diff de contrato

No CI, compare a versão atual com a anterior. Mudanças potencialmente incompatíveis incluem remover campo, tornar opcional em obrigatório, restringir enum ou excluir resposta.

Versionamento

Versione a API por contrato, não apenas pelo arquivo. Mudanças aditivas costumam ser compatíveis; alterações semânticas podem exigir nova versão ou período de depreciação.

Depreciação

deprecated: true

Comunique prazo, alternativa e telemetria de uso. Não remova uma operação apenas porque a documentação foi marcada.

Geração de cliente

Clientes gerados reduzem código repetitivo, mas dependem de operationIds e schemas estáveis. Revise tratamento de erros, retries e autenticação gerados.

Mock server

Mocks permitem frontend trabalhar antes do backend, mas exemplos devem cobrir erros e limites. Não confunda mock com comportamento real de autenticação ou performance.