Criar documentação da API

A criação da documentação da API para o repositório de código-fonte é muito importante. Uma boa documentação ajuda os desenvolvedores a entender, manter e usar sua API facilmente. A documentação completa explica como a API funciona, quais entradas ela precisa, quais saídas ela fornece e como usar os pontos de extremidade da API. Ao criar a documentação da API, você deve escolher o melhor formato (como especificação OpenAPI ou Markdown), incluir exemplos e cenários de uso, mantê-lo atualizado quando o código for alterado e solicitar comentários aos usuários da API para torná-lo melhor. Embora a abordagem geral da documentação da API funcione em todos os lugares, há algumas diferenças entre o Azure DevOps e o GitHub.

Criando documentação de API no Azure DevOps

Para adicionar a documentação da API a um projeto do Azure DevOps com eficiência, você deve usar uma ferramenta de documentação dedicada que funcione com seu fluxo de trabalho de desenvolvimento. As opções populares incluem Swagger (OpenAPI), API Blueprint e sistemas de documentação baseados em Markdown, como MkDocs ou Docusaurus. A integração do Azure DevOps ajuda a automatizar a criação da documentação e a mantém sincronizada com seu código. A maioria das ferramentas de documentação também pode ler comentários embutidos e incluí-los na documentação gerada automaticamente.

Você deve publicar a documentação da API em um local central que os membros da equipe e os stakeholders podem acessar. Pode ser um site de documentação dedicado, um wiki no Azure DevOps ou um portal de documentação externa.

Você também pode usar anotações ou decoradores diretamente em seu código para adicionar metadados que descrevem seus endpoints de API. Ferramentas como Swagger Codegen ou Springfox podem processar essas anotações e criar arquivos de especificação OpenAPI.

Configure processos automatizados em seu Azure Pipelines para criar a documentação da API automaticamente sempre que houver uma alteração no código. Isso garante que sua documentação permaneça atual e reflita as alterações mais recentes em suas APIs.

Criando documentação da API no GitHub

Ao usar o GitHub, considere criar a documentação da API usando 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 porque ela é amplamente compatível e fácil de usar. Defina uma estrutura consistente para documentos individuais, dividindo cada uma 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 facilitar o processo de criação de documentação de API com base em arquivos Markdown. As escolhas populares incluem Jekyll, MkDocs, Docusaurus e Hugo. Configure o gerador para ler arquivos Markdown e criar 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 o GitHub Pages, que permite hospedar sites estáticos diretamente do repositório GitHub. Você pode criar um branch dedicado para essa finalidade e enviar os arquivos HTML por push para esse branch. Você também pode usar 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 no código.

Configure 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 no código. Configure o fluxo de trabalho de automação para criar os arquivos de documentação HTML usando o gerador de documentação escolhido e implantá-los no GitHub Pages.