Aplicações para documentações de APIs

Em um mundo cada vez mais integrado e conectado, pode-se dizer que atualmente encontram-se diversos serviços que se comunicam entre si, trazendo uma vasta quantidade de funcionalidades e recursos que aprimoram a experiência de um usuário final, na utilização de algum software ou serviço.

A forma mais recorrente e usual de um software possibilitar a integração e oferta de seus serviços é através de uma API (Application Programmin Interface), classificada como um conjunto de rotinas e padrões, possibilitando a troca de informações entre sistemas, além de integrar serviços, empresas, negócios e parceiros.

O papel do desenvolvedor neste caso é desenvolver uma integração bem-sucedida, facilitando o seu processo. Pensando nisso, é necessário implementar, também, uma documentação que permita que qualquer pessoa, que não possua o pleno conhecimento do domínio da sua aplicação, desenvolva tais soluções de maneira eficaz e autônoma. Esta documentação pode ser criada manualmente ou automaticamente usando softwares e ferramentas específicas para este fim.

Figura 1 – Exemplo de Documentação API Spotify

Por que documentar uma API?

Uma API de sucesso busca engajar cada vez mais desenvolvedores. Um dos principais fatores que permitem este acontecimento está voltado a uma documentação bem elaborada. Uma API que não foi documentada adequadamente fará com que usuários gastem seu tempo tentando entender seu funcionamento, criando desta forma diversas barreiras para a devida utilização do serviço.

Ela é a chave para melhorar a experiência de uso de um desenvolvedor, algo conhecido também como dev friendly. Quanto mais completa, certificando-se que esteja seguindo boas práticas estabelecidas no modelo de arquitetura REST, mais desenvolvedores acharão sua utilização atrativa e agradável, levando assim a adoção de seus serviços, além de economizar tempo e custos relacionados a suporte.

Um dos focos de documentação para APIs são os recursos e endpoints disponibilizados, mas também é preciso lembrar que este documento deve ir além de apresentação de requisitos básicos, como a apresentação de algumas páginas em HTML sobre variações de retorno. Ela também precisa oferecer uma experiencia visual e interativa da API, proporcionando testes em tempo real.

Formas de documentação de APIs

Atualmente três especificações se destacam. Cada uma das ferramentas citadas abaixo pode apresentar foco em diferentes aspectos como legibilidade, design, curva de aprendizado e integração com outros serviços:

Swagger

Entre os diversos formatos de descrição de APIs que geram documentações dinamicamente, um dos mais conhecidos é o Swagger. De código aberto e em sua versão 2.0, permite que desenvolvedores projetem, construam, documentem e consumam APIs em RESTful.

Refere-se a uma ferramenta padrão de mercado, cujo objetivo é possibilitar que a documentação possa evoluir juntamente com a implementação da API, uma vez que a documentação pode ser gerada automaticamente.

Na hora de escrever a API, é necessário que os arquivos sejam criados no formato JSON, podendo facilitar o trabalho de desenvolvedores, ou torná-lo complexo demais para alguém que não esteja envolvido ou familiarizado com o código.

Algumas grandes empresas de tecnologia utilizam o Swagger em seus projetos, como Amazon, Netflix, Microsoft, Paypal, Getty Images, entre outras.

Figura 2 – Exemplo de utilização do Swagger

API Blueprint

Linguagem de descrição e especificação de APIs baseada em Marckdown, que facilita bastante a edição de documentos, mesmo por usuários não familiarizados com códigos. A maioria de suas ferramentas são de código aberto, sendo seu intuito garantir que desenvolvedores consigam projetar e criar protótipos de APIs em pouco tempo, além de documentar e realizar testes de APIs de missão crítica já implantadas.

Possui uma sintaxe simples e concisa, tornando assim a curva de aprendizagem mais rápida, uma leitura mais simples e fácil, pois suas seções são bem definidas e agrupadas por rota, onde cada rota pode apresentar vários métodos HTTP diferentes com nomes associados a cada método.

Figura 3 – Exemplo de utilização do API Blueprint

RAML

Acrônimo de RESTful API Modeling Language, é uma linguagem para descrever explicitamente API RESTful. Responsável facilitar o gerenciamento de ciclo de vida da API, o RAML é conciso, e faz legibilidade de uma API mais agradável ao ser humano.

Para documentar com o RAML, é possível optar por ferramentas de código aberto, como o console da API ou o HTML RAML 2. Tem como formato base o YAML, mas também é amplamente desenvolvido com base em outros padrões como JSON, e é neutro com ferramentas de linguagem como JAVA, Javascript, .Net, PHP, Python, Ruby, entre outras.

Um exemplo de utilização do RAML são as documentações feitas neste formato pelo Spotify e pela e.Pages.

Figura 4 – Exemplo de utilização do RAML

Conclusão

Em qualquer cenário, a ausência de material de documentação pode representar um afastamento de usuários em potencial. Para auxiliar neste processo oneroso, atualmente podemos contar com frameworks de documentação de APIs automatizados. As ferramentas mencionadas — Swagger, API Blueprint e RAML — apresentam recursos para criar automaticamente a documentação para todo o ciclo de vida de uma API.

Entretanto, documentar por si só através dessas ferramentas as vezes pode não ser suficiente. Um desenvolvedor deve manter seu trabalho atualizado, evitando documentações pobres ou obsoletas, já que uma API pode ser modificada a cada bug resolvido e a cada nova funcionalidade adicionada. Basicamente, o ideal sempre será documentar a API com as ferramentas corretas, além de regularmente atualizar o documento, garantindo uma melhor comunicação para todos os envolvidos no produto.

Autora: Amanda Maschio

Referências

https://medium.com/api-playbook/conhe%C3%A7a-as-3-principais-ferramentas-de-documenta%C3%A7%C3%A3o-de-apis-e78c959fb4e5

https://eltonminetto.dev/post/2017-06-29-definindo-apis-com-api-blueprint/

https://dev.delivery/documentacao-api-rest/#:~:text=Documenta%C3%A7%C3%A3o%20de%20API%20%C3%A9%20um,ferramentas%20espec%C3%ADficas%20para%20este%20fim.

https://developer.epages.com/apps/api-reference/resource-carts.html

https://www.alura.com.br/artigos/modelando-apis-rest-com-swagger?gclid=CjwKCAjw9e6SBhB2EiwA5myr9lbc78iv4U9RIH4xirirHPrjiHXVjckXvR0ah3exAHUZzstB8MxvRBoCaRwQAvD_BwE

https://imasters.com.br/apis-microsservicos/definindo-apis-com-o-api-blueprint

https://prensa.li/api-playbook/conheca-as-3-principais-ferramentas-de-documentacao-de-apis/

Deixe um comentário

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *