TL;DR
OpenAPI 3.1 adicionou compatibilidade total com JSON Schema, webhooks e melhorias no discriminador. O OpenAPI 3.2 adicionou suporte ao método QUERY, exemplos aprimorados e definições de segurança melhores. A Modern PetstoreAPI usa OpenAPI 3.2 para demonstrar todos os recursos mais recentes com exemplos prontos para produção.
Introdução
Você está escrevendo uma especificação OpenAPI. Você vê referências a OpenAPI 3.0, 3.1 e 3.2. Qual é a diferença? Você deveria atualizar? Suas ferramentas suportarão a nova versão?
OpenAPI evoluiu significativamente de 3.0 para 3.2. Cada versão adiciona recursos que tornam as especificações de API mais poderosas e precisas. Mas nem todas as ferramentas suportam as versões mais recentes, criando um desafio de compatibilidade.
O antigo Swagger Petstore usa OpenAPI 2.0 (especificação Swagger). A Modern PetstoreAPI usa OpenAPI 3.2, mostrando cada novo recurso com exemplos prontos para produção.
Neste guia, você aprenderá o que mudou em cada versão do OpenAPI, como escolher a versão certa e como a Modern PetstoreAPI demonstra os recursos do OpenAPI 3.2.
Linha de Base do OpenAPI 3.0
OpenAPI 3.0 (lançado em julho de 2017) foi uma grande atualização do Swagger 2.0.
Principais Recursos
1. Múltiplos servidores
servers:
- url: https://api.petstoreapi.com/v1
description: Production
- url: https://staging.petstoreapi.com/v1
description: Staging
Swagger 2.0 suportava apenas um host.
2. Objeto de corpo da requisição
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
Mais claro que o parâmetro `body` do Swagger 2.0.
3. Componentes para reusabilidade
components:
schemas:
Pet:
type: object
responses:
NotFound:
description: Resource not found
parameters:
PetId:
name: petId
in: path
Melhor organização que as `definitions` do Swagger 2.0.
4. Callbacks
Defina callbacks assíncronos (webhooks):
callbacks:
orderUpdate:
'{$request.body#/callbackUrl}':
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrderUpdate'
5. Links
Defina relacionamentos entre operações:
links:
GetPetByPetId:
operationId: getPetById
parameters:
petId: '$response.body#/id'
Limitações
1. Incompatibilidade com JSON Schema
OpenAPI 3.0 usava um subconjunto do JSON Schema Draft 5, não o JSON Schema completo. Isso causava problemas de validação.
2. Sem objeto webhooks
Webhooks eram definidos como callbacks, o que era confuso.
3. Discriminador limitado
O suporte a polimorfismo era básico.
4. Sem tipo nulo
Você não podia especificar `type: null` diretamente.
Principais Mudanças no OpenAPI 3.1
OpenAPI 3.1 (lançado em fevereiro de 2021) focou no alinhamento com o JSON Schema.
1. Compatibilidade Total com JSON Schema 2020-12
A maior mudança: Schemas OpenAPI 3.1 são JSON Schema 2020-12 válidos.
Antes (OpenAPI 3.0):
type: string
nullable: true # Específico do OpenAPI
Depois (OpenAPI 3.1):
type: [string, "null"] # Padrão JSON Schema
Benefícios:
- Use qualquer validador JSON Schema
- Compartilhe schemas entre OpenAPI e outras ferramentas
- Acesso a todos os recursos do JSON Schema
2. Objeto Webhooks
Antes (OpenAPI 3.0):
# Webhooks definidos como callbacks (confuso)
paths:
/subscribe:
post:
callbacks:
orderUpdate:
# definição do webhook
Depois (OpenAPI 3.1):
webhooks:
orderUpdate:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrderUpdate'
Separação mais clara entre endpoints de API e webhooks.
3. Discriminador Aprimorado
Melhor suporte a polimorfismo:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
discriminator:
propertyName: petType
mapping:
cat: '#/components/schemas/Cat'
dog: '#/components/schemas/Dog'
4. Identificador de Licença do Objeto Info
info:
license:
name: MIT
identifier: MIT # identificador SPDX
5. PathItem $ref
Referencie itens de caminho completos:
paths:
/pets:
$ref: '#/components/pathItems/PetsCollection'
Mudanças Disruptivas
- `nullable` removido
- Use `type: [string, "null"]` em vez disso.
- `exclusiveMinimum`/`exclusiveMaximum` alterado
- Agora booleano, não numérico.
- `example` vs `examples`
- Validação mais rigorosa.
Recursos Mais Recentes do OpenAPI 3.2
OpenAPI 3.2 (lançado TBD, rascunho disponível) adiciona padrões de API modernos.
1. Suporte ao Método QUERY
Método HTTP QUERY para buscas complexas:
paths:
/pets/search:
query: # Novo método
requestBody:
content:
application/json:
schema:
type: object
properties:
filters:
type: object
sort:
type: array
responses:
'200':
description: Search results
A Modern PetstoreAPI usa QUERY para buscas complexas de pets.
2. Exemplos Aprimorados
Múltiplos exemplos com metadados:
examples:
availableCat:
summary: Available cat
description: A cat available for adoption
value:
id: "019b4132-70aa-764f-b315-e2803d882a24"
name: "Fluffy"
species: "CAT"
status: "AVAILABLE"
adoptedDog:
summary: Adopted dog
value:
id: "019b4127-54d5-76d9-b626-0d4c7bfce5b6"
name: "Buddy"
species: "DOG"
status: "ADOPTED"
3. Definições de Segurança Aprimoradas
Melhor suporte a OAuth 2.0:
components:
securitySchemes:
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://petstoreapi.com/oauth/authorize
tokenUrl: https://petstoreapi.com/oauth/token
refreshUrl: https://petstoreapi.com/oauth/refresh
scopes:
pets:read: Read pets
pets:write: Create and update pets
orders:read: Read orders
4. Mapeamento de Discriminador Aprimorado
Polimorfismo mais flexível:
discriminator:
propertyName: type
mapping:
cat: Cat
dog: Dog
bird: '#/components/schemas/Bird' # Pode misturar local e $ref
5. Melhor Suporte à Depreciação
Deprecie campos específicos:
properties:
oldField:
type: string
deprecated: true
description: Use newField instead
newField:
type: string
Como a Modern PetstoreAPI Usa o OpenAPI 3.2
A Modern PetstoreAPI mostra todos os recursos do OpenAPI 3.2.
1. Especificação Completa
A especificação completa do OpenAPI 3.2 está disponível em:
https://petstoreapi.com/openapi.json
2. Método QUERY para Buscas Complexas
/pets/search:
query:
summary: Search pets with complex criteria
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PetSearchQuery'
3. Webhooks
webhooks:
petStatusChanged:
post:
summary: Pet status changed
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PetStatusWebhook'
4. Schemas Polimórficos
Pet:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Bird'
discriminator:
propertyName: species
5. Exemplos Abrangentes
Cada endpoint inclui múltiplos exemplos mostrando diferentes cenários.
6. Respostas de Erro RFC 9457
responses:
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
Veja a especificação OpenAPI completa para todos os recursos.
Guia de Migração
3.0 para 3.1
1. Substitua `nullable` :
# Antes
type: string
nullable: true
# Depois
type: [string, "null"]
2. Atualize `exclusiveMinimum` / `exclusiveMaximum`:
# Antes
minimum: 0
exclusiveMinimum: true
# Depois
minimum: 0
exclusiveMinimum: 0
3. Mova os webhooks:
# Antes
paths:
/subscribe:
callbacks:
# webhook
# Depois
webhooks:
# webhook
3.1 para 3.2
1. Adicione métodos QUERY onde apropriado:
/pets/search:
query: # Novo no 3.2
# complex search
2. Aprimore os exemplos:
examples:
example1:
summary: Description
value: {...}
3. Atualize as definições de segurança:
Adicione `refreshUrl` aos fluxos OAuth.
Testando Especificações OpenAPI com Apidog
Apidog suporta todas as versões do OpenAPI.
Importar Especificação OpenAPI
1. Abra o Apidog
2. Clique em "Importar"
3. Selecione "OpenAPI 3.x"
4. Cole a URL ou carregue o arquivo
5. Apidog valida e importa
Validar Especificação
Apidog verifica:
- Validade do schema
- Integridade da referência
- Correção dos exemplos
- Completude da definição de segurança
Testar Implementação de API
Gere casos de teste a partir da especificação:
- Validação da requisição
- Validação da resposta
- Verificações de código de status
- Conformidade do schema
Comparação de Versões
Importe múltiplas versões e compare:
- Mudanças disruptivas
- Novos endpoints
- Mudanças de schema
- Campos depreciados
Conclusão
OpenAPI evoluiu significativamente:
OpenAPI 3.0: Base com servidores, corpos de requisição, callbacks
OpenAPI 3.1: Compatibilidade com JSON Schema, objeto webhooks, melhor polimorfismo
OpenAPI 3.2: Método QUERY, exemplos aprimorados, segurança melhorada
A Modern PetstoreAPI usa OpenAPI 3.2 para demonstrar todos os recursos com exemplos prontos para produção. É a implementação de referência para o design de API moderno.
Use Apidog para trabalhar com qualquer versão do OpenAPI, validar especificações e testar implementações.
Perguntas Frequentes (FAQ)
Devo atualizar para OpenAPI 3.1 ou 3.2?
Se suas ferramentas suportam, sim. A compatibilidade com JSON Schema do OpenAPI 3.1 é valiosa. O OpenAPI 3.2 adiciona padrões modernos como o método QUERY.
Minha especificação OpenAPI 3.0 funcionará com ferramentas 3.1?
Em sua maioria, sim, mas `nullable` e `exclusiveMinimum`/`exclusiveMaximum` precisam de atualizações.
Os geradores de código suportam OpenAPI 3.2?
O suporte está crescendo. Verifique a documentação do seu gerador. Muitos suportam 3.1, menos suportam 3.2.
Posso usar os recursos do OpenAPI 3.2 no 3.1?
Não. Use a versão que corresponde aos seus recursos. Se precisar do método QUERY, use o 3.2.
Como valido minha especificação OpenAPI?
Use Apidog para importar e validar sua especificação. Ele verifica a validade do schema e a integridade da referência.
Onde posso ver um exemplo completo de OpenAPI 3.2?
A Modern PetstoreAPI fornece uma especificação OpenAPI 3.2 completa e pronta para produção.
Qual a diferença entre webhooks e callbacks?
Webhooks são requisições HTTP de servidor para cliente. Callbacks são definidos no OpenAPI 3.0 como parte das operações. O OpenAPI 3.1+ possui um objeto `webhooks` dedicado.
Devo usar JSON ou YAML para especificações OpenAPI?
Ambos funcionam. YAML é mais legível para humanos. JSON é mais fácil para ferramentas. A Modern PetstoreAPI fornece ambos os formatos.