Termos Swagger e OpenAPI

Enquanto escrevia o artigo anterior, que nunca é publicado, percebi que muitos não entendem a diferença entre os termos Swagger e OpenAPI (OAS) . As pessoas usam os dois termos de forma intercambiável. Não os culpo, pois tive as mesmas dúvidas.

O Swagger permite que você descreva a estrutura de suas APIs para que as máquinas possam lê-las.
— SwaggerIO

Se você tentar pesquisar no Google Swagger ou OpenAPI , na maioria dos casos, você acabará no SwaggerIO , o site oficial do Swagger. Se você me perguntar, o site obscureceu o propósito do Swagger desde o primeiro dia. Não intencionalmente, no entanto. Informação não falta, só não é apresentada de forma clara e concisa.

A Especificação OpenAPI (OAS) define uma interface independente de linguagem padrão para APIs RESTful que permite que humanos e computadores descubram e entendam os recursos do serviço sem acesso ao código-fonte, documentação ou por meio de inspeção de tráfego de rede.
— SwaggerIO

Hoje, existem muitos artigos sobre esse assunto, então é muito mais fácil perceber a diferença, mas ainda é possível encontrar escritos que misturam os termos. SwaggerIO está promovendo o Swagger como um conjunto de ferramentas e o OpenAPI como uma especificação. Poderíamos dizer que o Swagger é usado para criar a especificação OpenAPI . Essencialmente, esta afirmação não está errada, mas não é toda a verdade.

Uso dos termos

Normalmente, os desenvolvedores usam o termo Swagger em, pelo menos, dois contextos:

• descrever um conjunto de ferramentas para implementar a especificação. Algumas ferramentas são Swagger Editor, Swagger UI, Swagger Codegen, etc. É um ecossistema.
• para descrever a especificação da versão 2.*.*

Os desenvolvedores usam o termo OpenAPI Specification 3 principalmente em um único contexto:

• para descrever a especificação da versão 3.*.*. A comunidade refere-se a OAS, OAS3, OpenAPI Spec, OpenAPI 3 Specification, etc. Eles adotaram o OpenAPI 3 como o sucessor da Swagger Specification 2.

Swagger e OpenAPI são amigos íntimos por um motivo. A história é o ingrediente chave aqui.

A empresa SmartBear mantém Swagger. Em novembro de 2015, a Linux Foundation anunciou que está criando, junto com SmartBear, Google, Microsoft, Paypal e algumas outras empresas, uma nova organização, OpenAPI Initiative. A principal tarefa da iniciativa era estender a especificação Swagger.

Alguns meses depois, a iniciativa renomeou Swagger para especificação OpenAPI. A iniciativa clonou o código para o novo repositório. A partir desse ponto, os indivíduos usaram ambos os termos em vários contextos.

Palavra final

O Swagger costumava ser um tudo-em-um, especificação e conjunto de ferramentas. Hoje, Swagger é um conjunto de ferramentas. OpenAPI é uma especificação. É isso.

É bom saber a diferença. No entanto, qualquer que seja o termo que você use, o outro lado o entenderá - no final, isso é a única coisa que importa.