Referencia OpenAPI 3.0

Gratuito DevTools

Referencia OpenAPI 3.0

Guia interativo da especificacao OpenAPI/Swagger 3.0 com todos os objetos, campos obrigatorios e opcionais, exemplos em YAML e JSON, security schemes e snippets prontos para usar.

5.3k usuarios Atualizado em Mar 2026 4.9/5

Avalie esta ferramenta:

4.9 (876 votos) Obrigado!

Info Object

Metadados sobre a API. O campo info e obrigatorio na raiz do documento OpenAPI.

Campo	Tipo	Status	Descricao
title	string	obrigatorio	Nome da API.
version	string	obrigatorio	Versao da API (ex: "1.0.0").
description	string	opcional	Descricao da API, suporta Markdown.
termsOfService	string (url)	opcional	URL dos termos de servico.
contact	Contact Object	opcional	Informacoes de contato do responsavel pela API.
license	License Object	opcional	Informacoes de licenca da API.

# YAML
openapi: "3.0.3"
info:
  title: Minha API
  version: "1.0.0"
  description: |
    API de exemplo para demonstracao.
    Suporta **Markdown**.
  contact:
    name: Suporte
    email: api@exemplo.com

Paths Object

Define os endpoints disponiveis na API. Cada chave e um caminho relativo a URL base.

Campo	Tipo	Descricao
/{path}	Path Item Object	Caminho relativo. Pode incluir parametros de caminho: `/usuarios/{id}`
summary	string	Sumario do Path Item (opcional, sobrescrito por operacoes).
parameters	Parameter[]	Parametros comuns a todas as operacoes do path.

paths:
  /usuarios:
    get:
      summary: Listar usuarios
      operationId: listarUsuarios
    post:
      summary: Criar usuario
  /usuarios/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer

Operation Object

Campo	Tipo	Status	Descricao
operationId	string	opcional	Identificador unico da operacao. Deve ser unico no documento.
summary	string	opcional	Resumo curto da operacao.
description	string	opcional	Descricao detalhada. Suporta Markdown.
tags	string[]	opcional	Tags para agrupamento na UI.
parameters	Parameter[]	opcional	Lista de parametros aceitos.
requestBody	Request Body Object	opcional	Corpo da requisicao (POST/PUT/PATCH).
responses	Responses Object	obrigatorio	Respostas possiveis da operacao.
security	Security Req[]	opcional	Esquemas de seguranca para esta operacao.
deprecated	boolean	opcional	Marca a operacao como depreciada.

Parameter Object

Campo	Tipo	Status	Descricao
name	string	obrigatorio	Nome do parametro.
in	string	obrigatorio	Localizacao: `query`, `header`, `path`, `cookie`.
required	boolean	opcional	Obrigatorio para parametros de path. Padrao: false.
schema	Schema Object	opcional	Tipo e validacoes do parametro.
description	string	opcional	Descricao do parametro.
example	any	opcional	Exemplo de valor.
deprecated	boolean	opcional	Marca como depreciado.

Request Body Object

Campo	Tipo	Status	Descricao
content	Map[string, Media Type]	obrigatorio	Tipos de midia aceitos. Ex: `application/json`.
required	boolean	opcional	Se o corpo e obrigatorio. Padrao: false.
description	string	opcional	Descricao do corpo da requisicao.

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

Responses Object

Codigo	Descricao
200	OK — Requisicao bem-sucedida.
201	Created — Recurso criado com sucesso.
204	No Content — Sem corpo na resposta.
400	Bad Request — Requisicao invalida.
401	Unauthorized — Nao autenticado.
403	Forbidden — Sem permissao.
404	Not Found — Recurso nao encontrado.
422	Unprocessable Entity — Validacao falhou.
500	Internal Server Error — Erro no servidor.
default	Resposta padrao para outros codigos.

Schema Object

Campo	Tipo	Descricao
type	string	`string`, `number`, `integer`, `boolean`, `array`, `object`
format	string	`int32`, `int64`, `float`, `double`, `date`, `date-time`, `uuid`, `email`
properties	Map[string, Schema]	Propriedades do objeto.
required	string[]	Lista de propriedades obrigatorias.
items	Schema Object	Tipo dos itens do array.
enum	any[]	Valores permitidos.
$ref	string	Referencia a outro schema: `#/components/schemas/Nome`
nullable	boolean	Permite valor null.
example	any	Exemplo de valor para o campo.
minLength / maxLength	integer	Tamanho minimo/maximo de strings.
minimum / maximum	number	Valor minimo/maximo para numeros.
pattern	string	Expressao regular para validacao de string.

Components Object

Repositorio de objetos reutilizaveis referenciados com $ref.

Campo	Descricao
schemas	Definicoes de Schema (modelos de dados).
responses	Respostas reutilizaveis.
parameters	Parametros reutilizaveis.
requestBodies	Corpos de requisicao reutilizaveis.
securitySchemes	Esquemas de autenticacao/autorizacao.
headers	Headers HTTP reutilizaveis.

Security Schemes

Bearer JWT

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

# Aplicar globalmente:
security:
  - bearerAuth: []

API Key (Header)

apiKeyAuth:
  type: apiKey
  in: header
  name: X-API-Key

OAuth2 (Authorization Code)

oauth2:
  type: oauth2
  flows:
    authorizationCode:
      authorizationUrl: https://auth.exemplo.com/oauth/authorize
      tokenUrl: https://auth.exemplo.com/oauth/token
      scopes:
        read:usuarios: Leitura de usuarios
        write:usuarios: Escrita de usuarios

Snippets Comuns

Paginacao (query params)

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

Resposta de erro padrao

components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string

Metodos HTTP no OpenAPI

Metodo	Uso tipico	Body	Idempotente
GET	Ler/listar recursos	Nao	Sim
POST	Criar recurso	Sim	Nao
PUT	Substituir recurso completo	Sim	Sim
PATCH	Atualizacao parcial	Sim	Nao necessariamente
DELETE	Remover recurso	Opcional	Sim

Como Usar Esta Referencia

Consulte qualquer objeto da especificacao OpenAPI 3.0 em segundos.

Use a busca

Digite o nome do campo ou objeto no campo de busca para filtrar o conteudo.

Navegue pelo menu

Clique em qualquer secao no menu lateral para ir diretamente ao objeto desejado.

Consulte os exemplos

Cada objeto tem exemplos em YAML prontos para copiar e usar no seu projeto.

Veja os snippets

A secao Snippets Comuns traz templates prontos para paginacao, erros e autenticacao.

Sobre a Especificacao OpenAPI 3.0

O OpenAPI Specification (OAS) e um padrao aberto para descrever APIs RESTful. A versao 3.0, lancada em 2017, trouxe melhorias significativas em relacao ao Swagger 2.0, incluindo suporte a multiplos servidores, callbacks e schemas mais expressivos.

Principais diferencas do OpenAPI 3.0 para o Swagger 2.0:

Campo host, basePath e schemes foram substituidos por servers
O campo definitions passou para components/schemas
Request bodies agora sao objetos proprios (nao mais parametros in: body)
Suporte a oneOf, anyOf e not no Schema Object
Links e callbacks foram adicionados como novos conceitos

Artigo

OpenAPI 3.0: O Guia Completo para Documentar APIs REST em 2026

Por Equipe Chipak • Atualizado em Mar 2026 • 8 min de leitura

Neste artigo

O que e o OpenAPI Specification
Estrutura de um documento OpenAPI
Principais objetos e como usa-los
Autenticacao e seguranca
Ferramentas do ecossistema
Boas praticas de design

1. O Que E o OpenAPI Specification

O OpenAPI Specification (OAS), anteriormente conhecido como Swagger, e o padrao de mercado para descrever APIs RESTful de forma legivel tanto por humanos quanto por maquinas. Mantido pela OpenAPI Initiative (parte da Linux Foundation), ele permite que equipes descrevam endpoints, parametros, autenticacao, schemas de dados e exemplos de requisicao/resposta em um unico arquivo YAML ou JSON.

A versao 3.0 representa uma evolucao significativa do Swagger 2.0, com maior expressividade, suporte nativo a multiplos servidores e uma separacao mais clara entre os conceitos de caminho, operacao e schema. Hoje, OpenAPI 3.0 e aceito por praticamente todas as ferramentas de API management, gateways e geradores de codigo do mercado.

2. Estrutura de um Documento OpenAPI

Um documento OpenAPI valido precisa conter pelo menos tres campos obrigatorios na raiz:

openapi: versao da especificacao (ex: "3.0.3")
info: metadados da API (titulo e versao sao obrigatorios)
paths: mapa de endpoints disponiveis

Alem dos campos obrigatorios, um documento completo tipicamente inclui servers (URLs base), components (objetos reutilizaveis), security (autenticacao global) e tags (agrupamento de operacoes).

"Um bom documento OpenAPI e a documentacao viva da sua API — ele nao apenas descreve o que a API faz, mas permite gerar clientes, servidores, testes e documentacao interativa automaticamente."

3. Principais Objetos e Como Usa-los

O coracaoo do OpenAPI e o Path Item Object, que descreve cada endpoint. Dentro de cada caminho, voce define operacoes por metodo HTTP (get, post, put, patch, delete). Cada operacao deve ter pelo menos o campo responses.

O Schema Object e o mais rico e reutilizavel — ele define a forma dos dados usando um subconjunto do JSON Schema. Voce pode definir schemas em components/schemas e referenciar em qualquer lugar com $ref, evitando repeticao e mantendo consistencia.

O Parameter Object descreve entradas em quatro locais: query (string de consulta), path (segmento da URL), header (cabecalho HTTP) e cookie. Parametros de path sao sempre obrigatorios.

4. Autenticacao e Seguranca

O OpenAPI 3.0 suporta quatro tipos de esquema de seguranca, definidos em components/securitySchemes:

http: autenticacao HTTP basica ou Bearer (JWT)
apiKey: chave de API em header, query ou cookie
oauth2: fluxos OAuth2 completos (authorization code, client credentials, implicit, password)
openIdConnect: descoberta via OpenID Connect URL

Voce pode aplicar seguranca globalmente no campo security da raiz ou por operacao individual. Para endpoints publicos em uma API autenticada, use security: [] na operacao especifica para sobrescrever o global.

5. Ferramentas do Ecossistema

Um dos maiores beneficios do OpenAPI e o ecossistema de ferramentas construido em torno do padrao:

Swagger UI / Redoc / Scalar: geradores de documentacao interativa a partir do arquivo OpenAPI
OpenAPI Generator: gera clientes SDK em mais de 50 linguagens e frameworks de servidor
Prism (Stoplight): servidor mock que simula sua API a partir do documento
Spectral: linter para validar e aplicar regras de qualidade no seu OpenAPI
Postman / Insomnia: importam documentos OpenAPI para criar colecoes de testes
AWS API Gateway / Kong / Apigee: gateways que importam OpenAPI para configuracao

6. Boas Praticas de Design

Para criar documentos OpenAPI de alta qualidade, siga estas diretrizes:

Use operationId unico e descritivo em cada operacao — e a base para nomes de funcoes em SDKs gerados
Prefira $ref para schemas repetidos em vez de definir inline — facilita manutencao
Documente todos os codigos de resposta possiveis, incluindo erros 4xx e 5xx
Use tags para agrupar operacoes logicamente — melhora a navegacao na documentacao
Inclua examples reais nos schemas e parametros — acelera o entendimento do consumidor
Versione sua API no campo info.version e, opcionalmente, no path (ex: /v1/usuarios)

Referencia OpenAPI 3.0

Secoes

Bearer JWT

API Key (Header)

OAuth2 (Authorization Code)

Paginacao (query params)

Resposta de erro padrao

Como Usar Esta Referencia

Sobre a Especificacao OpenAPI 3.0

OpenAPI 3.0: O Guia Completo para Documentar APIs REST em 2026

1. O Que E o OpenAPI Specification

2. Estrutura de um Documento OpenAPI

3. Principais Objetos e Como Usa-los

4. Autenticacao e Seguranca

5. Ferramentas do Ecossistema

6. Boas Praticas de Design