[Gastosabertos-dev] Doc API

[Andres MRM]

Estou em dúvida sobre a documentação para a API.
Pelo que eu vi, não existe uma única forma de utilizar JSON Hyper-Schema para
definir uma API. Logo acho que faria mais sentido pautarmos nossa Schema de
acordo com o que a ferramenta de gerar a doc quiser. Para isso precisamos
definir a ferramenta.

Minha ideia inicial era uma lib em Python que recebesse uma Schema
representando uma API e cuspisse um site bonitinho com toda a documentação.
Não achei.

Parece que o mais próximo disso é isso em Ruby:
https://github.com/interagent/prmd
Aparentemente ele cospe a doc em MarkDown.

O pacote que você tinha comentado, Edgar:
https://github.com/lbovet/docson
Parece que é mais para representar um objeto em JSON Schema, e não uma API
completa. O que não impede que façamos um site, e usemos um DocSon para
representar cada endpoint. Porém, pelo que vi, você inclui ele na sua página
via iframe, então teríamos vários iframes...

Tem também um tal de Swagger:
http://swagger.io/
Onde parece que você define sua API em um YAML e ele gera "tudo" para você:
http://editor.swagger.io/
Mas não ficou claro para mim o que seria esse "tudo".
O DocSon parece que consegue se relacionar com esse Swagger, mas também não
entendi direito como ou no que consiste essa relação...

Outra opção é gerar a Doc na mão em Python a partir do Schema...


A ideia da doc da API é estar em um site a parte só para isso, ou junto com
o site principal?


Ps.:
Aqui um cara do Heroku explica mais ou menos como fazer um Schema para API nos
moldes da do Heroku: https://brandur.org/elegant-apis