A Open API Initiative (OAI) é uma iniciativa focada em criar, evoluir, engajar e promover um formato de especificação de APIs open source baseado em Swagger, a ser utilizado por produtores de APIs e fornecedores neutros de softwares comerciais. Trata-se de uma representação poderosa e fácil de aprender que o desenvolvedor pode utilizar em projetos para documentar suas APIs REST.
A especificação do Open API é aberta e está no GitHub, pode ser utilizada sem que seja necessário pagar por seu uso, assim como participar sendo contribuinte de sua especificação, bastando para tal se cadastrar no fórum de especificação do site. Empresas como MundoAPI (sim! nos cadastramos como membros), Apigee, Intuit, Paypal, Microsoft, Google, 3Scale, participam da iniciativa OpenAPI. Estas e muitas outras já entenderam que esta iniciativa é importante para a padronização do uso e da documentação de APIs, feita com Swagger.
Abaixo listamos ferramentas e projetos Swagger para criação e manipulação de especificação de APIs:
| Ferramentas | Descrição |
| Swagger Core | Bibliotecas em Java para gerar e ler definições Swagger. |
| Swagger Codegen | Ferramenta em linha de comando para gerar tanto o cliente quando o servidor. Este feito a partir de uma definição Swagger. |
| Swagger UI | Interface gráfica para explorar as definições de APIs baseadas em Swagger. |
| Swagger Editor | Editor para a criação de definições YAML ou JSON. |
| Swagger JS | Conjunto de bibliotecas javascript para o consumo de APIs especificadas com o Swagger, que podem ser utilizadas com aplicações clientes e node.js. |
| Swagger Node | Módulo Swagger para node.js. |
| Swagger-Socket | Expõe e invoca definições de APIs feitas com Swagger em WebSockets. |
| Swagger Parser | Biblioteca independente para parsing de Java. |
A ferramenta mais importante na hora de especificar a sua API é o Swagger Editor. Este tem um papel fundamental na estratégia e abordagem API First, onde a criação do software se inicia na concepção de um conjunto de APIs, que são importantes tanto para a interoperabilidade entre sistemas como para o negócio. Com API First em mente e com o Swagger Editor, o desenvolvedor deve especificar o seu conjunto de APIs logo no início do projeto, desta forma seu sistema já estará concebido para atender a diversos tipos de clientes possíveis, como mobile, IoT, Web, etc.
Após a especificação das primeiras APIs, o desenvolvedor pode utilizar o seu gerenciamento de APIs favorito. A líder nas três últimas edições do Gartner é o Apigee Edge da Google, originalmente da empresa Apigee, que foi comprada pela Google em 2016 e representada no Brasil pela SeedTS. O Apigee Edge utiliza a especificação de API padrão Swagger como uma das alternativas para a criação de API Proxy em sua plataforma. Além de ser mais rápido a criação do API Proxy, esta já fica com a documentação gerada durante a fase de especificação (lembra do API First?). O mesmo Swagger também será posteriormente útil para o desenvolvimento do backend e esta abordagem chama-se top down.
No passado não muito distante com uma abordagem semelhante, a de modelagem canônica em SOA, existia uma grande dificuldade e trabalho extra de conversão, entre contrato de serviço em formato word e o código. Já com o auxílio de ferramentas que seguem a OpenAPI esse caminho é suave e automático. Como exemplo, na figura abaixo se encontra ao lado direito a especificação Swagger e no esquerdo a documentação gerada automaticamente. Após esse passo, o desenvolvedor pode também gerar a sua API Proxy em um clique no gerenciador de APIs, o que torna o trabalho top down muito mais rápido. Mas, se quiser mesmo gerar tudo até o serviço de backend ou mesmo clientes, pode-se usar o Swagger CodeGen.
Uma outra abordagem é a bottom-up, que basicamente é o inverso da top-down. Na bottom-up usualmente se expõe o legado via APIs Proxies também em um gerenciador de APIs junto com a sua documentação Swagger.
Ah! Uma informação adicional: A mesma documentação gerada para a API será útil para o seu Portal de APIs. Portais de APIs possuem o papel de se relacionar com os desenvolvedores internos e externos, assim como gerenciar o permissionamento e autorização para o uso das APIs, que você criou com tanto afinco!
Bem, agora você sabe que Open API Initiative é uma iniciativa aberta e que utiliza o Swagger como elemento principal para especificação de APIs, agora você pode começar aplicando API First e utilizando o Swagger na abordagem top-down! Boa API!
Antonio Bruce Gois (Linkedin) – Arquiteto\Dev. eterno e Fundador e CEO do Portal Mundo API e da consultoria SeedTS, com mais de dez anos de experiência na definição e implantação de soluções com SOA e nos últimos anos com API e Microserviços. Entusiasta de Marketing e ex-palestrante nacional e internacional.