Como documentar uma API a ser criada?

Olá Flavio, tudo bem?

Peço desculpa pela demora para responder o seu tópico.

Documentar a criação de uma API é fundamental para garantir que todos os envolvidos no projeto estejam alinhados e saibam exatamente o que deve ser feito. Uma boa prática é criar um documento que descreva o escopo da API, incluindo informações como:

• Objetivos e metas do projeto
• Requisitos funcionais e não-funcionais
• Arquitetura da solução
• Fluxos de dados e processos
• Detalhes técnicos, como linguagem de programação, banco de dados, etc.

Quanto à padronização, existem algumas opções, como o OpenAPI (antigo Swagger), que você havia comentado, e o RAML. Essas ferramentas permitem que você defina a estrutura da sua API, incluindo endpoints, parâmetros, respostas, etc.

Além disso, é importante que a documentação esteja sempre atualizada e acessível a todos os envolvidos no projeto.

Espero ter ajudado. Caso ainda tenha alguma dúvida com relação a este tópico, estarei à disposição para ajudá-lo.

Grande abraço e bons estudos!