Criar documentação da API
Documentar a API de um repositório de código-fonte é essencial para fornecer clareza, acessibilidade e facilidade de uso aos desenvolvedores que mantêm e consomem a API. A documentação abrangente serve como um guia para entender a funcionalidade, as entradas, as saídas e o uso dos pontos de extremidade da API. Ao documentar a API, você deve selecionar o formato de apresentação mais adequado (como especificação OpenAPI ou Markdown), incluindo exemplos e cenários de uso, mantê-lo atualizado com alterações de código e solicitar comentários dos consumidores da API para melhorar continuamente sua qualidade.
Embora a abordagem geral para documentar uma API seja independente de plataforma, existem algumas diferenças entre o Azure DevOps e o GitHub em termos de implementação.
Documentação da API no Azure DevOps
Para adicionar a documentação da API a um projeto do Azure DevOps da maneira mais eficiente, considere utilizar uma ferramenta de documentação dedicada ou uma plataforma que se integre ao fluxo de trabalho de desenvolvimento. As opções populares nesta categoria incluem Swagger (OpenAPI), API Blueprint e sistemas de documentação baseados em Markdown, como MkDocs ou Docusaurus. Seus recursos de integração do Azure DevOps ajudam a automatizar o processo de geração de documentação, mantendo-o sincronizado com a base de código. A maioria das ferramentas de documentação também dá suporte à análise de comentários embutidos e incluí-los na documentação gerada automaticamente.
Você deve publicar a documentação da API em uma localização central acessível aos membros da equipe e aos stakeholders. Pode ser um site de documentação dedicado, um wiki no Azure DevOps ou um portal de documentação externa.
Como alternativa, você pode usar anotações de código ou decoradores diretamente em seu código para adicionar metadados que descrevem seus pontos de extremidade de API. As ferramentas como Swagger Codegen ou Springfox são capazes de processar essas anotações e gerar os arquivos de especificação OpenAPI.
Configure os processos automatizados em seu Azure Pipelines para gerar a documentação da API automaticamente sempre que houver uma alteração na base de código. Isso garante que sua documentação permaneça atualizada e reflita as alterações mais recentes em suas APIs.
Documentar a API no Github
Ao usar o GitHub, considere gerar a documentação da API aproveitando as ferramentas que fazem parte do ecossistema do GitHub.
Comece documentando seus pontos de extremidade da API, operações, parâmetros, respostas e quaisquer outras informações relevantes. Considere criar essa documentação no formato Markdown para dar conta de seu amplo suporte e facilidade de uso. Defina uma estrutura consistente de documentos individuais, dividindo cada um em seções que descrevem autenticação, pontos de extremidade, parâmetros de solicitação, exemplos de resposta, etc.
Assim como acontece com o Azure DevOps, você pode usar geradores de documentação ou geradores de site estáticos para simplificar o processo de geração de documentação de API a partir de arquivos Markdown. As opções mais populares incluem Jekyll, MkDocs, Docusaurus e Hugo. Configure o gerador para analisar os arquivos Markdown e gerar páginas HTML estáticas. Você pode personalizar o layout, o tema e o estilo para corresponder à identidade visual e às preferências do projeto.
Para publicar o conteúdo HTML, use GitHub Pages, que permitem hospedar sites estáticos diretamente do repositório GitHub. Você pode criar um branch dedicado para essa finalidade e efetuar push dos arquivos HTML para esse branch. Você também pode implementar o GitHub Actions para compilar e implantar automaticamente a documentação da API sempre que houver uma alteração nos arquivos de documentação ou na base de código.
Configure ao GitHub Actions para criar e implantar automaticamente a documentação da API sempre que houver uma alteração nos arquivos de documentação ou na base de código. Configure o fluxo de trabalho de automação para gerar os arquivos da documentação HTML usando o gerador de documentação escolhido e implante-os no GitHub Pages.