Swagger e o Open API Initiative
Já falamos sobre RAML aqui no blog. Uma maneira de descrever APIs, facilitando a vida de clientes, fornecedores, e até mesmo máquinas. Acontece que há uma alternativa muito mais popular, chamada Swagger, que na minha opinião tem por principal ponto positivo ser base para a criação da OpenAPI Specification.
Se até aqui tudo isso pareceu "sopa de letrinhas", keep calm! Vamos abrir o glossário e detalhar termo por termo.
Swagger: Um framework completo
As vantagens de utilizar o Swagger são basicamente as mesmas de usar RAML (ou API Blueprint): Modelar e documentar APIs REST.
O Swagger é um framework, composto por diferentes ferramentas, que ajudam no desenvolvimento de APIs. Dentre essas ferramentas podemos destacar as de código aberto:
- Swagger Editor: Um editor poderosíssimo que pode ser usado online, e que facilita (e muito) na escrita de arquivos Swagger.
- Swagger UI: Uma plataforma para a geração e publicação da documentação de APIs.
- Swagger Codegen: Esse aqui é o meu favorito. Através da especificação da sua API, cria SDKs para diferentes linguagens.
- Swagger Inspector: Para fechar com chave de ouro. O Inspector é um serviço que testa APIs com base em um contrato Swagger.
Além disso temos o SwaggerHub, que "empacota" isso tudo em um Software As A Service, prometendo aumentar produtividade e colaboração entre times no que tange desenvolvimento de APIs.
Nos items acima citei "arquivos Swagger" e "contrato Swagger". Bem... hoje o Swagger (framework) é apto a trabalhar com o Swagger (especificação). Mas não é apenas essa especificação que ele suporta.
E é aqui que a SmartBear (empresa por trás do desenvolvimento da "marca" Swagger) aparece e merece aplausos.
Swagger Specification vira OpenAPI Specification
Deixa eu corrigir o primeiro parágrafo do capítulo anterior:
As vantagens de utilizar o OpenAPI Spec são basicamente as mesmas de usar RAML Spec, Swagger Spec, ou API Blueprint Spec: Modelar e documentar APIs REST.
Com uma vantagem a mais: Ser aberta*. (note o asterisco)
O Swagger Specification desde o seu princípio é de código aberto. Mas sempre teve uma empresa vinculada ao seu desenvolvimento (mais ou menos o que acontece com a MuleSoft e o RAML).
Em janeiro de 2016, a SmartBear Software renomeou a Swagger Specification para OpenAPI Specification. Disponibilizando-a no Github em github.com/OAI/OpenAPI-Specification, e tornando-a assim em uma especificação "vendor-neutral".
Isso tudo, claro, com supervisão do consórcio que a mesma SmartBear ajudou a construir: O Open API Initiative. Que é também "curador" do OpenAPI Specification e tem como integrantes alguns gigantes da indústria como Google, IBM, Microsoft, e as próprias MuleSoft e SmartBear.
Swagger & OpenAPI
Novamente, deixa eu corrigir o parágrafo do primeiro capítulo:
As vantagens de utilizar Swagger com OpenAPI Spec são: Além de confiar em uma especificação aberta e vendor-neutral, você ainda conta com o poderoso ferramental de código aberto provido pelo Swagger.
O Swagger "gira em torno" do OpenAPI, provendo ferramentas para a modelagem e documentação. É sem dúvida uma combinação espetacular, e não a toa é a mais famosa e eficiente no momento.
Considerações finais
Confesso que eu tive problemas para entender o relacionamento entre RAML, Swagger e OpenAPI, principalmente por ter adotado o RAML e não seguido o desenvolvimento do Swagger.
Hoje, se você for usar OpenAPI (você deveria) é improvável que não recorra ao Swagger para produzir os seus documentos. Portanto, não é incomum vermos muitos materiais onde esses dois conceitos se misturam e aparentam ser um só.
No próximo post sobre Swagger, vamos para uma abordagem mais prática, mostrando como utilizar as ferramentas com OpenAPI.
Até a próxima.