API do jeito certo – Como documentar API?

Agora que você já sabe o que é uma API, deve ter ficado a dúvida: como saber quais métodos estão disponíveis, como acessá-los? Quais parâmetros e qual o seu tipo? E caso você ainda não tenha se perguntado, vou perguntar por você: E como saber quais APIs estão disponíveis para serem acessadas? Como documentar a sua API é o tema deste artigo.

Quais são as ferramentas (ou padrões) de documentação existentes?

Só há uma situação em que “nenhuma documentação” é melhor que “qualquer documentação”: Quando ela, a documentação, está desatualizada. Documentação e comentários de código sofrem desse mesmo mal, cuja solução é sempre a mesma: Automatização à partir do código. No caso de puro código, nós temos os testes de unidade, que servem como algum tipo de documentação #theTruthIsOnTheCode. Mas e a documentação? Esta fatalmente vai exigir algum grau de esforço manual. Para casos como esse, a recomendação geral é que “quando mais próximo do código, melhor”.

Nesse sentido, você vai encontrar ferramentas como RAML ou ReDOC, que ou implementam um padrão próprio de documentação, ou que fazem uso do já consolidado padrão OpenAPI. Do meu ponto de vista, a minha recomendação é que você utilize a ferramenta “padrão” da stack que você está utilizando. Em geral, essas ferramentas fazem uso da própria documentação do código para gerar uma interface – muitas vezes funcional e que permite interação – para o backend.

Para WebAPIs escritas em C#, há a biblioteca Swashbuckle, que através da documentação feita em código, gera uma interface que permite a interação com backend, mas que principalmente, gera uma documentação extremamente detalhada da sua API. Vale muito a pena investir algum tempo de estudo na especificação OpenAPI. Cada dia mais ela se torna presente em todos os lugares.

O que é a OpenAPI Initiative?

A OpenAPI Initiative trata-se de uma iniciativa sob a tutela da Linux Foundation. Criada por um consórcio de empresas, a OAI é a responsável por manter – e isso também quer dizer evoluir – aquilo que eles chamam de “a vendor neutral description format”. Ou traduzindo: um padrão de descrição/documentação que seja neutro em relação a qualquer fornecedor.

Entre as empresas que formaram o consórcio está a SmartBean. E como você sabe, a SmartBean era a antiga detentora do Swagger. E é por esse motivo que a OpenAPI é tão parecida com o Swagger; e também é por esse mesmo motivo que ainda hoje vemos tantas pessoas confundindo Swagger com OpenAPI.

Ainda que o padrão possua uma versão de escrita compatível com JSON, a versão em YAML é muito mais agradável de ser lida e escrita. A definição do padrão você pode conferir na própria pagina da OpenAPI (www.openapis.org). Mas sempre é possível já começar com a mão na massa, acessando um editor online, onde é possível escrever a sua documentação, e validá-la com direto a hints e tudo o mais. A ferramenta é o https://editor.swagger.io. Ao acessá-la pela primeira vez, você verá uma definição de exemplo: A Swagger Pet Store. Com base nesse exemplo já é possível fazer os seus primeiros rascunhos de definição de API.

Agora que você já sabe quais as ferramentas…

Como documentar APIs?

Documente tudo. Quanto maior o escopo da sua API (se ela é pública, por exemplo) mais você deve se preocupar com a documentação. Imagine que as pessoas que vão integrar com a sua API, estão completamente fora do seu contexto; não compartilham do mesmo glossário de palavras, não conhecem a metáfora que guiou o time nas decisões que tomou. Uma documentação rica ajuda essa pessoa ser mais independente, no que diz respeito a utilizar a sua integração (e assim você tem mais tempo de continuar evoluindo o seu produto ao invés de ficar explicando mil vezes a mesma coisa).

Por melhor que você seja em documentação, sempre vai ter alguém com uma dúvida. A especificação OpenAPI possui uma definição de cabeçalho para documentação que envolve a publicação de dados para contato. Não ignore isso. Deixe sempre disponível o contato da pessoa responsável pela API. E prefira anotar um contato da pessoa que é responsável técnica pela API. Ou melhor ainda, algum contato que leve ao time responsável. Nada pior do que você entrar em contato com alguém que não está mais na companhia.

Sempre descreva os endpoints. Por mais óbvio que pareça pra você, para outras pessoas pode não ser. Principalmente serviços de borda em domínios. Conceitos que possuem o mesmo nome, podem significar coisas totalmente distintas ou terem comportamentos peculiares. Você tem uma tag Users, então acrescente uma descrição que diga se são usuários do sistema ou qualquer outra coisa.

Ainda assim, tome muito cuidado e não repita o óbvio. E com isso quero dizer que uma descrição como “Retorna os usuários” não agrega muito valor. Algo como “Retorna uma lista paginada com dados resumidos do usuário. Para dados detalhados, acesse o endpoit XPTO” é muito melhor. Com esse texto você está ensinando alguém a utilizar a sua API. E é exatamente isso o que as boas documentações fazem: Elas ensinam.

Não ignore a documentação dos objetos de response/request. Diga qual é o papel deles no contexto. As vezes o próprio nome já ajuda (XPTOPaginatedSummary, por exemplo), mas isso não diminui a obrigação de explicar. Quanto as propriedades, explique o conceito por trás de cada uma. O mesmo para a lista de parâmetros. E se houver uma referência cruzada (esse valor é o fruto da pesquisa de um outro endpoint), deixe um link para saber onde obter o valor. Não negligencie a lista de valores válidos para um campo. Especifique enums e sempre que possível, não faça uso de números mágicos.

Especifique os HTTP Status code e o formato de resposta. Não há nada pior para um frontender escrevendo testes do que não saber as possíveis situações de retorno. Ou ainda, o formato dos objetos no response. Então, ao escrever sua documentação, não deixe de especificar todos os objetos e seus respectivos HTTP Status Code.

Documentar o tipo de autenticação não é apenas importante para tornar a interface swagger funcional. Ela também ajudará o time que está se integrando com a sua API.

E como saber quais APIs estão disponíveis para uso? (Bônus)

Conforme a companhia cresce, maior torna-se a necessidade de integração. Imagine você ser abordado diariamente por pessoas querendo saber se você tem uma API para isso ou aquilo? Ou ainda “Hei! Tem como você me passar o endereço do seu swagger?”. Você provavelmente passaria alguns dias sem fazer nada, só respondendo mensagens. Esse é um outro problema e cada vez mais as empresas estão sofrendo com ele: o controle do catálogo de APIs.

Muito provavelmente você já ouviu falar de API Manager – ou somente APIM. Trata-se de uma solução que é capaz de gerenciar o API Gateway, além de controlar tráfego, gerenciar versões, oferecer protótipos, controlar uso e tudo o que for relativo a integrações via API. Se a sua solução está rodando em alguma cloud, provavelmente você já tem um APIM à disposição. E mesmo assim, ainda existem outras opções. As mais conhecidas, sem dúvida, são o Kong e a Sensedia.

O mais importante é: o APIM pode (e deve) ser atualizado com a mesma documentação da sua API. E isso deve acontecer toda vez que ela sofrer alguma alteração. Dessa forma, os demais times ou parceiros, uma vez logados no APIM, podem procurar por recursos e integrações, conhecer os pré-requisitos e restrições, automatizando e muito o trabalho de integração entre sistemas.

Agora que você sabe como documentar a sua API, está na hora da gente aprender como fazer isso no código! Te vejo no próximo artigo!