Adotar ferramenta de documentação de contrato da API

[yrachid]

Contexto

Existem algumas linguagens e ferramentas que ajudam na documentação e padronização de APIs. A ApiBlueprint, por exemplo, é uma linguagem que provê uma forma similar ao Markdown para escrever documentação. Existe um pequeno ecossistema de ferramentas em torno deste padrão, desde plataformas colaborativas para centralização de informações, como o Apiary até executores de teste de contrato, que analisam a resposta da aplicação contra a especificação do ApiBlueprint. Ferramentas como Aglio e Dredd, por exemplo, adicionariam ao projeto, respectivamente, um gerador de documentação para os endpoints escritos em ApiBlueprint e testes de Contrato baseados na nossa Blueprint.

[wcalderipe]

Concordo que vamos precisar de uma documentação para os futuros desenvolvedores do projeto entenderem a API. Queria saber se temos outras opções e além do ApiBlueprint e quais os prós e contras.

O que pensa da seguinte especificação?
QUANDO eu tiver um novo endpoint ou alteração de um existente
EU QUERO escrever essa documentação de forma simples
ENTÃO gerar uma documentação em HTML ou Markdown