Conheça as 3 principais ferramentas de documentação de APIs
Conheça as 3 principais ferramentas de documentação de APIs
Engajar desenvolvedores é fundamental para uma API de sucesso. Boa parte disso se deve a documentação bem elaborada. Se uma API não for documentada adequadamente, muito provavelmente o usuário gastará seu tempo tentando entender o seu funcionamento, o que acaba criando barreiras no uso do serviço.
Um dos focos deste documento são os recursos e endpoints disponibilizados e é preciso lembrar que não basta apresentar algumas páginas HTML sobre variações de retorno, como realizar autenticação e o qual a função de cada recurso. A documentação de APIs vai além destes requisitos básicos, mas precisa oferecer uma experiência mais visual e interativa da API, ou seja, proporcionando um teste em tempo real delas.
No mercado podem ser encontradas diversas ferramentas para auxiliar na elaboração de uma boa documentação interativa para os recursos da sua API.
Atualmente três especificações se destacam entre as demais:
Cada uma das ferramentas acima apresenta foco em diferentes aspectos como legibilidade, design, curva de aprendizado, integração com outros serviços. A seguir vamos entender suas particularidades:
Tornando sua documentação mais intuitiva com Swagger
Entre os diversos formatos de descrição de APIs que geram a documentação dinamicamente, o mais conhecido é o Swagger. Ele é de código aberto e permite que desenvolvedores e equipes projetem, construam, documentem e consumam APIs em RESTful. Atualmente se encontra em sua versão 2.0.
Trata-se de uma ferramenta padrão de mercado, cujo objetivo é possibilitar que a documentação evolua juntamente com a implementação da API, uma vez que a documentação pode ser gerada automaticamente. Grandes empresas de tecnologia como Amazon, Netflix, Apigee, Getty Images, Microsoft e Paypal já adotam Swagger em seus produtos e projetos, principalmente em função da facilidade de integração com o código fonte.
Na hora de descrever a API é preciso que os arquivos sejam criados no formato JSON. Se por um lado isso facilita o trabalho de programadores, por outro pode ser algo complexo demais para alguém que não esteja tão envolvido com o código.
O Swagger é capaz de ajudar desenvolvedores de APIs REST a:
Modelar APIs;
Gerar documentação automatizada da API;
Gerar códigos do cliente e do servidor, suportando diversas linguagens de programação;
Testar funcionalidades da API.
Para realizar tais tarefas o Swagger precisa especificar a OpenAPI, uma linguagem para descrever contratos de APIs REST. Ela delimita um formato JSON com campos padronizados para que o usuário consiga descrever recursos, modelo de dados, URIs, Content-Types e métodos HTTP aceitos .
Além da OpenAPI, o Swagger dispõe um conjunto de ferramentas e as principais são:
Swagger Editor
Swagger UI
Swagger Codegen
O módulo de UI permite que desenvolvedores interajam intuitivamente com as APIs em sandbox. Já o Editor é uma ferramenta online que possibilita documentar de forma mais interativa usando YAML. Um dos benefícios do Editor é seu portfólio contendo templates de documentos que servem de base para quem não deseja iniciar do “zero” a documentação.
Além disso, uma de suas principais funções do Editor é de que ao iniciar um novo projeto o usuário pode definir a toda a estrutura de sua API e assim gerar o código em uma linguagem de sua preferência
Quanto ao Swagger Codegen, a partir da descrição em YAML cria automaticamente o “esqueleto” da API com documentação em diferentes linguagens de programação.
A documentação para APIs pode ser feita de três formas:
Manualmente: o desenvolvedor escreve livremente as especificações da API e as publica posteriormente em seu próprio servidor.
Automaticamente: simultaneamente ao desenvolvimento da API é gerada a documentação.
Codegen: converte todas as anotações contidas no código fonte das APIs REST em documentação
A documentação interativa da API por meio do Swagger ainda inclui endpoints da API REST que detalham payloads, cabeçalhos, parâmetros, métodos HTTP necessários para solicitações e informações de código de erro.
Vale lembrar que investir em uma documentação mais interativa com o Swagger traz vantagens para o desenvolvedor que deseje futuramente consumir sua API, pois ele torna a integração desta mais rápida e de maior qualidade.
A facilidade de leitura do API Blueprint
Trata-se de uma linguagem de descrição e especificação de APIs baseada em Markdown, o que facilita a edição dos materiais por usuários que não estão familiarizados com códigos. A maior parte de suas ferramentas são open source, já que seu intuito é garantir que o desenvolvedor consiga projetar e criar protótipos de APIs em menos tempo, além de documentar e testar as APIs de missão crítica já implantadas.
Sua sintaxe é simples e concisa, mas ainda sim expressiva, permitindo que ela seja acessível a todos os envolvidos no ciclo de vida de uma API.
Há outros padrões muito conhecidos no mercado como o Swagger, mencionado acima, porém a curva de aprendizagem da API Blueprint é mais rápida. Quanto a leitura ela é fácil, pois as seções são bem definidas e agrupadas por rota, sendo que cada rota pode apresentar vários métodos HTTP diferentes com nomes associados a cada método
A documentação nesse caso mostra:
Atributos listados com suas descrições
Exemplos de solicitações
Respostas desses exemplos
No caso do Blueprint, duas são as ferramentas integradas a ele que se destacam:
Dredd
Permite que o serviço de back-end seja testado com base na documentação da API. Dessa forma os problemas de atualização da documentação em questão podem ser resolvidos. A ferramenta é capaz de suportar linguagens como PHP, Python, Ruby, Perl, Node.js ou Go
Drakov
Permite que serviços simulados sejam iniciados e testados com solicitações/respostas adaptadas à documentação da API, o que pode ser visto como uma banco de ensaio.
RAML: de desenvolvedores para desenvolvedores
Trata-se de um acrônimo para RESTful API Modeling Language, logo RAML é uma linguagem para descrever explicitamente API RESTful. Além de tornar mais fácil o gerenciamento do ciclo de vida da API, o RAML é conciso e faz a legibilidade da API mais amigável ao ser humano.
Para documentar sua API com RAML, você pode optar por ferramentas open source como o Console da API ou o HTML RAML 2. A documentação pode ser gerada rapidamente, sendo que os analisadores disponíveis em vários idiomas permitem que a criação de documentos personalizados e scripts interativos, como Spotify.
O RAML 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.
No caso do YAML, não se trata de uma linguagem de marcação, mas de uma para realizar a descrição de dados de maneira legível para desenvolvedores. Tal descrição, por ser muito utilizada por desenvolvedores facilita a compreensão do RAML, que suporta muitas práticas de reutilização e ajuda na criação de sua documentação a partir de pequenos blocos de construção.
Apesar disso, optar pelo RAML possui algumas desvantagens como ser destinado a APIs RESTful, dessa forma se sua Web API não seguir os mesmos princípios é possível que você não consiga usar o RAML adequadamente. Tal qual o API Blueprint, ele não se ajusta bem no caso de APIs não HTTP.
Outro ponto que se deve ter atenção é quanto a linguagem. O YAML é direcionado para desenvolvedores, ou seja, se este não utilizar uma ferramenta de design para criar a API ou a documentação, a equipe sem conhecimentos técnicos poderá ter dificuldades.
Documentação constantemente atualizadas
Como você pode ver as três ferramentas que citei acima são bons exemplos para manter sua API com um bom nível de documentação. Uma dica valiosa é se preocupar com este aspecto — a documentação — logo na concepção da API, assim o desenvolvimento e documentação podem caminhar juntos.
Em qualquer cenário, a ausência de material pode representar um afastamento de usuários em potencial. O lado bom é que hoje 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 sua API.
Entretanto documentar por si só através dessas ferramentas não é o suficiente. É necessário que você como desenvolvedor mantenha seu trabalho atualizado, evitando documentações pobres ou obsoletas. Isso por que as APIs são modificadas a cada bug resolvido e nova funcionalidade são adicionada, ou seja, documentar sua API com as ferramentas corretas e regularmente atualizar o documento garante uma melhor comunicação para todos os envolvidos no produto.