Criar documentação da API

Criar documentação de API para seu 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 dá 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ê-la atualizada quando o código for alterado e pedir feedback aos usuários da API para melhorá-la. 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 documentação de API a um projeto de DevOps do Azure de forma eficiente, você deve usar uma ferramenta de documentação dedicada que funcione com seu fluxo de trabalho de desenvolvimento. 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 de 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 as partes interessadas possam acessar. Pode ser um site de documentação dedicado, um wiki no Azure DevOps ou um portal de documentação externo.

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

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

Criando documentação de API no GitHub

Ao usar o GitHub, considere criar documentação de 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 é amplamente suportada e fácil de usar. Defina uma estrutura consistente para 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áticos para facilitar o processo de criaçã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 ler arquivos Markdown e criar 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, use as Páginas do GitHub, que permitem hospedar sites estáticos diretamente do repositório do GitHub. Você pode criar uma ramificação dedicada para essa finalidade e enviar os arquivos HTML para essa ramificação. Você também pode usar 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 no 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 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 implante-os nas Páginas do GitHub.