Olá desenvolvedores,
Esta postagem é para esclarecer as principais diferenças entre a especificação de API aberta 2.0 e 3.0. Saber as principais diferenças não compatíveis ajudará na migração da especificação 2.0 para a especificação 3.0.
1. Versão
Como saber se a definição da API está aderindo à especificação 2.0 ou 3.0?
Na especificação 2.0, há uma propriedade chamada "swagger" que informa a versão da especificação, por exemplo
"swagger": "2.0"
3.0
Isso é substituído pela nova propriedade "openapi" e deve ser usada da seguinte forma,
"openapi": "3.0.0"
2. Servidores Múltiplos
A especificação da API aberta 2.0 tem espaço apenas para um host ou detalhes de um servidor e não tem suporte para ter informações de vários servidores. Essa limitação é tratada na especificação 3.0, agora existe um novo array de objetos de servidores onde você pode ter informações de host com quaisquer espaços reservados de variáveis na URL do host também.
Exemplo:
"servers": [
{
"url": "https://{username}.gigantic-server.com:{port}/{basePath}",
"description": "O servidor da API de produção",
"variables": {
"username": {
"default": "demo",
"description": "este valor é atribuído pelo provedor de serviços, neste exemplo `gigantic-server.com`"
},
"port": {
"enum": [
"8443",
"443"
],
"default": "8443"
},
"basePath": {
"default": "v2"
}
}
}
]
No exemplo acima, a URL tem campos de usuário, porta e basepath como campos de variáveis (placeholders), que são descritos na seção de objetos de variáveis e também valores padrão podem ser fornecidos para cada um deles.
A renderização desses detalhes de vários servidores no Swagger UI é mostrada abaixo,
3. Componentes
A especificação da API aberta 3.0 fornece um objeto de componentes que pode conter esquemas, parâmetros, respostas, exemplos, esquemas de segurança, links, corpos de solicitação, cabeçalhos e callbacks. Este objeto de componente não afetará a API até que seja referenciado em algum lugar na API.
Vantagem: Se várias operações de uma API precisarem de uma estrutura de entrada semelhante, a estrutura de entrada pode ser definida como corpos de solicitação no componente e pode ser reutilizada em vários caminhos. Da mesma forma, cabeçalhos, respostas e assim por diante podem ser reutilizados.
"components": {
"schemas": {
"Category": {
"type": "object",
"properties"