Este tópico lista algumas ferramentas conhecidas que são usadas para documentar APIs. Tenha em mente que esta lista não é definitiva e nem delimitadora.
Os frameworks de documentação de APIs facilitam a geração do conteúdo, pois trabalham com arquivos que seguem o padrão do Open API Specification (OAS).
Quando as pessoas estão desenvolvendo uma API, é possível gerar o arquivo na especificação OAS a partir do código-fonte contendo toda a documentação de referência dessa API. Então, os frameworks permitem importar o arquivo de especificação e gerar uma saída com a documentação formatada e organizada.
Existem frameworks gratuitos e pagos. Muitos deles permitem personalizar a aparência da documentação gerada, com diferentes níveis de personalização.
Estes são alguns frameworks conhecidos para gerar documentação de APIs:
O Markdown é uma linguagem bastante utilizada para criar documentação de APIs e software em geral, pelo fato de ser flexível e amplamente compatível com a metodologia docs-as-code.
Algumas das vantagens são:
Documentar APIs em Markdown facilita a criação de conteúdo conceitual sobre a API. Por outro lado, se a documentação de referência for escrita manualmente em Markdown, isso pode impedir ou dificultar a atualização, a automação e o compartilhamento do conteúdo. Por isso, o Markdown pode ser uma boa alternativa para escrever a documentação conceitual da API, mas pode não ser muito ágil para criar a documentação de referência. Outra dificuldade que pode aparecer é no caso de APIs extensas: quanto maior a API for e mais parâmetros ela tiver, mais trabalhoso vai ser criar a documentação de referência manualmente.
Por isso, uma boa prática é integrar o Markdown com o conteúdo do arquivo de especificação OAS. A documentação precisa evoluir junto com o produto e precisa de manutenção constante. Frameworks e ferramentas próprias para documentação têm recursos que facilitam a manutenção e a publicação do conteúdo.
O Markdown pode ser escrito em qualquer editor de texto convencional, mas existem ferramentas que permitem ver o resultado final do conteúdo enquanto estiver escrevendo. Estas são algumas dessas ferramentas: