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, entradas, saídas e 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 as alterações de código e solicitar feedback dos consumidores da API para melhorar continuamente sua qualidade.
Embora a abordagem geral para documentar a API seja agnóstica em relação à plataforma, há algumas diferenças em sua implementação entre o Azure DevOps e o GitHub.
Documentando a API no Azure DevOps
Para adicionar documentação de API a um projeto de DevOps do Azure da maneira mais eficiente, você deve considerar a utilização de uma ferramenta ou plataforma de documentação dedicada que se integre ao seu 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 documentação de geração, mantendo-o sincronizado com a base de código. A maioria das ferramentas de documentação também suporta a análise de comentários embutidos e a sua inclusão na documentação gerada automaticamente.
Você deve publicar a documentação da API em um local central acessível aos membros da sua equipe e partes interessadas. Pode ser um site de documentação dedicado, um wiki no Azure DevOps ou um portal de documentação externo.
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. Ferramentas como Swagger Codegen ou Springfox são capazes de processar essas anotações e gerar os arquivos de especificação OpenAPI.
Configure processos automatizados em seus Pipelines do Azure para gerar documentação de 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.
Documentando a API no Github
Ao usar o GitHub, considere gerar documentação de API aproveitando ferramentas que fazem parte do ecossistema do GitHub.
Comece documentando seus pontos de extremidade de API, operações, parâmetros, respostas e quaisquer outras informações relevantes. Considere criar essa documentação no formato Markdown para levar em conta 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 no Azure DevOps, você pode usar geradores de documentação ou geradores de site estático para simplificar o processo de geração de documentação de API a partir de arquivos Markdown. As opções populares incluem Jekyll, MkDocs, Docusaurus e Hugo. Configure o gerador para analisar arquivos Markdown e gerar páginas HTML estáticas. Você pode personalizar o layout, o tema e o estilo para corresponder à marca e às preferências do seu projeto.
Para publicar o conteúdo HTML, aproveite as Páginas do GitHub, que permitem hospedar sites estáticos diretamente do repositório do GitHub. Você pode criar para essa finalidade uma ramificação dedicada e enviar os arquivos HTML para essa ramificação. Você também pode implementar as Ações do GitHub para criar e implantar automaticamente sua documentação de API sempre que houver uma alteração nos arquivos de documentação ou na base de código.
Configure as Ações do GitHub para criar e implantar automaticamente sua documentação de 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 de documentação HTML usando o gerador de documentação escolhido e implante-os nas Páginas do GitHub.