Para que uma API tenha sucesso no mercado e seja muito utilizada, ela precisa ter uma boa documentação, que forneça ao usuário o que ele precisa para prosseguir com o seu desenvolvimento de software.
Mas, pode ser difícil criada uma documentação de forma manual, principalmente quando é feita separadamente do desenvolvimento do código original. Além disso, o resultado final pode não agradar ou ajudar quem precisa utilizar a sua API.
Com isso, é comum ver as documentações de APIs serem deixadas de lado porque não estão de acordo com as atualizações e novas funcionalidades que o programa possa receber. Isso faz com que os desenvolvedores não conheçam novos endpoints ou não saibam o que esperar da resposta de cada solicitação.
Para evitar esse problema e facilitar o desenvolvimento de software, você pode utilizar duas soluções juntas que prometem automatizar a criação da documentação e torná-la mais objetiva aos seus usuários. Quer conhecê-las? É só continuar a leitura!
O que são Swagger e OpenAPI?
Para compreender melhor essas soluções, precisamos entender o conceito de cada uma e como elas acabaram se conectando e oferecendo diversas vantagens para os desenvolvedores que as utilizam no momento de criar uma documentação.
Vamos começar pelo Swagger,um framework que permite aos desenvolvedores descrever a estrutura da sua API de uma forma simples. A partir dessa descrição, a ferramenta consegue ler a estrutura e gerar automaticamente uma documentação para ela ou ler uma documentação e gerar uma API.
Já o OpenAPI é uma especificação que visa padronizar o desenvolvimento de APIs REST. Essa especificação é aberta e está no GitHub para ser utilizada sem precisar pagar pelo seu uso. O desenvolvimento dela é fomentado pela OpenAPI Iniciative, formada por mais de 30 empresas de tecnologia, incluindo Microsoft, Google e IBM.
Agora que você já sabe o que o Swagger e o OpenAPI significam, deve estar se perguntando como e onde as duas podem trabalhar juntas. A resposta para isso é bem simples.
Para implementar a utilização da especificação OpenAPI é necessário utilizar ferramentas que podem ser encontradas no framework Swagger.
A partir de ferramentas como o editor, o visualizador ou gerador de bibliotecas, o Swagger permite aos desenvolvedores manipularem a especificação da OpenAPI para gerar suas documentações.
Swagger vs OpenAPI: qual é a diferença?
Pela definição das soluções, vemos que a principal diferença entre elas está no seu uso.
Enquanto o OpenAPI é uma especificação, o Swagger é um conjunto de ferramentas que permitem implementar o OpenAPI.
Porém, quando o Swagger surgiu, ele já possuía a sua própria especificação, conhecida como especificação Swagger. Mas, após um tempo do seu surgimento, o Swagger foi comprado pela empresa chamada SmartBear. Com a aquisição, a nova companhia doou a especificação Swagger para a OpenAPI Initiative.
Ao realizar esse processo, a OpenAPI Iniciative oficialmente mudou o nome da especificação para OpenAPI. A especificação continua a mesma, porém com o nome da nova empresa que a detém.
Como usar Swagger e OpenAPI no desenvolvimento de software?
Até aqui, vimos que Swagger e o OpenAPI são soluções que trabalham juntas para ajudar você no desenvolvimento e, principalmente, na documentação da sua API. Mas como essas tecnologias interagem na prática para ajudar no desenvolvimento de softwares?
Bom, para criar e manipular a especificação do OpenAPI, é necessário utilizar um editor de texto para fazer o desenvolvimento de software. Como essa especificação foi criada inicialmente pelo Swagger, nada melhor do que utilizar as ferramentas que ele oferece.
Uma das ferramentas é o Swagger Editor, que permite escrever o código da OpenAPI enquanto mostra o que o código está gerando. Um dos benefícios de utilizá-lo é que é possível arrumar facilmente qualquer erro no código, sem precisar esperar que ele execute todo o código para então mostrá-los.
Além do editor, o Swagger também oferece outras ferramentas interessantes para o desenvolvedor utilizar, como o Swagger Core que disponibiliza bibliotecas em Java para gerar e ler as definições Swagger, ou então o Swagger JS que disponibiliza um conjunto de bibliotecas javascript para as APIs. Para conhecer mais ferramentas, você pode conferir este post no blog da GR1D.
Para usar as soluções, também é importante aprender como utilizar a especificação da OpenAPI. Esse aprendizado pode levar um tempinho, mas é essencial para você conseguir utilizar o Swagger e o OpenAPI com maestria!
Para ajudar você nessa jornada, separamos dois recursos que podem auxiliar no aprendizado sobre a especificação OpenAPI:
- Você pode aprender a partir dessa documentação do GitHub ,que oferece um bom ponto de partida para você entender a base da especificação OpenAPI;
- Caso você queira algo mais amigável visualmente, pode aproveitar o Guia de Uso Swagger, mais fácil de seguir com muitos exemplos.
Você pode ainda utilizar os dois recursos juntos para se aprofundar na especificação e ver vídeos no Youtube que ajudem a visualizar como ela é feita na prática. Ao fazer isso, se atente ao conteúdo e busque aqueles que mostram a versão mais recente da OpenAPI, a 3.0.
Como escrever uma descrição OpenAPI?
Se você já aprendeu o funcionamento da especificação, pode prosseguir o seu desenvolvimento de software criando a descrição da OpenAPI. A partir dela, você conseguirá gerar a sua documentação de forma muito mais fácil e prática. Para ajudar você, separamos abaixo quatro dicas para iniciar a descrição do OpenAPI.
#1 Use as linguagens JSON ou YAML
Os arquivos OpenAPI são feitos com as linguagens JSON ou YAML. Elas utilizam a mesma estrutura de dados, porém apresentam diferenças na sua sintaxe.
Para a maioria dos desenvolvedores web, o JSON pode ser mais familiar já que é muito semelhante ao JavaScript. Porém, ele é uma linguagem menos legível para os humanos. No entanto, isso parece não incomodar muito já que a maioria dos provedores de API adotam esse formato.
Por outro lado, a linguagem YAML faz mais uso de espaços em branco e possui poucas marcações, o que ajudam a torná-la mais legível. Na hora de decidir qual das duas utilizar, você pode se decidir à vontade, escolhendo aquela que você está mais acostumado ou gostaria de aprender.
Isso acontece porque os arquivos feitos tanto em JSON quanto em YAML podem ser convertidos entre eles, oferecendo mais liberdade ao desenvolvedor na hora de escolher qual linguagem utilizar no desenvolvimento de software.
#2 Conheça a estrutura básica
Um ponto muito importante ao trabalhar com OpenAPI e Swagger é conhecer a sua estrutura básica. Caso você vá desenvolver manualmente, é interessante começar com um modelo para nortear suas operações. Geralmente, os códigos possuem essa estrutura:
| Nome | Definição |
| Metadata | Essa parte aparece no início do código e mostra a versão do Swagger seguido de informações como título, descrição e versão da sua API. |
| Base URL | É formada pelos atributos host, basePath e schemes e representa uma quebra da URL completa da sua API. |
| Consumes and Produces | Descreve os tipos de aplicações suportadas pela API. |
| Paths | Aqui é onde o endpoint individual da sua API é definido, assim como o método HTTP suportado por ele. |
| Parameters | Definição dos tipos de parâmetros, obrigatoriedade, formatos, entre outros detalhes importantes. |
| Responses | Para cada parâmetro, você pode definir os códigos de status para ele, como usar o 400 para Not Found ou 200 para OK. |
| Schema | Parte do response onde você define a qual scheme ele estará referenciando. |
| Authentication | Local onde se define a segurança e métodos de autenticação da sua API. |
Para conhecer cada parte da estrutura, de forma mais aprofundada, você pode conferir a documentação completa da especificação.
#3 Desenvolva no seu editor preferido
Por mais que você possa utilizar o Swagger Editor, existem diversas outras ferramentas onde a especificação OpenAPI pode ser manipulada para você escrever a descrição dela. Basicamente, qualquer outro editor de texto que você utilize nos códigos pode ser usado para escrever a descrição da API.
Porém, geralmente, os demais editores não conseguem ser tão rápidos como o Swagger Editor na hora de verificar os erros. Para isso, você pode tentar encontrar plugins que forneçam essa verificação.
No VS Code, por exemplo, existe um plugin de código aberto chamado openapi-lint que verifica os arquivos JSON e YAML e analisa se eles estão de acordo com a especificação OpenAPI.
#4 Faça descrições de uma API existente
Caso você já tenha uma API em desenvolvimento, pode conseguir documentá-la em um arquivo OpenAPI. Se seu código for construído em um framework comum, como Rails (Ruby) ou Falcon (Python), ele já está pronto para criar uma descrição OpenAPI.
Se você utilizou frameworks diferentes, pode se beneficiar de um serviço conhecido como Optic, que consegue ouvir o tráfego da sua API, revisar suas solicitações e respostas ao vivo e assim gerar um arquivo OpenAPI.
Quais são as melhores práticas para usar no Swagger e OpenAPI?
Agora que você já sabe como criar a descrição OpenAPI, pode pensar que o trabalho já acabou, não é mesmo? Mas, na realidade, antes de criá-la já é preciso se atentar a boas práticas que ajudarão a sua documentação a ficar mais acessível para os usuários.
Por isso, separamos a seguir quatro boas práticas para você usar no Swagger e OpenAPI e, assim, garantir mais qualidade no desenvolvimento de software.
Desenvolva descrições amigáveis
Para garantir uma boa documentação, é interessante você se colocar no lugar do usuário que vai utilizá-la no desenvolvimento de software e verificar se as informações adicionadas realmente ajudam no desenvolvimento.
Na descrição, é necessário descrever o que são cada endpoints, como cada método é utilizado e quais são seus parâmetros e o significado das suas respostas. Por isso, na hora de criar sua descrição OpenAPI, tente deixá-la o mais completa possível evitando o surgimento de dúvidas quanto ao uso da sua API.
Crie boas nomenclaturas
Os endpoints da sua API precisam ter um nome legível e que as pessoas consigam identificá-los enquanto conferem a sua documentação. Para isso, o ideal é evitar nomes com vários números e letras misturados e criar rótulos legíveis.
Além da legibilidade, manter a constância na nomenclatura também é importante. Em vez de manter rótulos nomeados como “lastName” e “First_Name” na mesma documentação, é interessante adotar um padrão com o seu time e optar por uma das versões para nomear seus rótulos de forma consistente.
Utilize padrões REST
Às vezes, o melhor que um desenvolvedor pode fazer é manter as convenções estabelecidas. Quando a maioria dos desenvolvedores já estão habituados com um padrão específico, pode ser mais interessante continuar com o padrão do que tentar ser original, mas acabar não sendo entendido por muitos.
No caso das APIs, desenvolvê-las utilizando a arquitetura REST pode ser mais interessante já que é frequentemente utilizada no desenvolvimento de APIs, e mais conhecida no mercado. Ao fazer isso, você facilita o entendimento da sua aplicação, já que a base dela foi feita em algo que a maioria já conhece.
Pense nas atualizações futuras
Todos os programas existentes passam por mudanças e atualizações, e com a sua API o processo não será diferente. Portanto, toda vez que surgir uma nova atualização, a sua documentação precisa seguir isso também.
Quando for desenvolver a descrição OpenAPI, pense em maneiras de gerenciar a sua documentação e fazer com que a atualização dela possa acontecer de forma automática.
Com todas essas informações, você já consegue ter um bom ponto de partida de como ter a documentação para sua API de forma simples, para que ela ajude outros programadores no desenvolvimento de software.
Se você quer continuar consumindo conteúdos como esse, confira o blog da GR1D e aprenda mais sobre o mundo das APIs!
