[Gastosabertos-dev] Doc API

Domingo Março 8 22:31:53 UTC 2015

Testei o PRMD. Ajustei o Schema que tinha feito para o modelo dele e gerei
alguma coisa para ver como fica. Por algum motivo quando a página em HTML é
gerada no servidor a partir do MD está ficando defeituoso:
http://site.gastosabertos.org/docapi/
Aqui na minha máquina está funcionando... Talvez seja a lib que usa o pandoc
ou a falta do pandoc no servidor. Onde está o código do site no servidor? Só
achei as builds...

(troquei a lib de interface com Pandoc por uma mais ativa,
https://github.com/bebraw/pypandoc, e que não tem o
caminho para o pandoc na máquina do autor "hardcoded" =P )

De qualquer forma, o GH está renderizando o MD de forma semelhante a como a
página está ficando na minha máquina:
https://github.com/okfn-brasil/gastos_abertos_website/blob/master/pages/pt_BR/docapi.md
Assim dá para ter uma noção do conteúdo que o PRMD gera a partir desse Schema:
https://github.com/andresmrm/gastos_abertos/blob/master/gastosabertos/receita/schemas/revenue-list_prmd.json

Para ser sincero achei mais ou menos...
O principal problema que vi é que a documentação da entrada do endpoint é
quase inexistente (é possível que eu não tenha visto alguma
funcionalidade, mas tenho a impressão que não, pois segui o exemplo deles).
Ele também gera a tabela sem uma linha espaçada em baixo e em cima, o que quebra
a conversão MD->HTML do Pandoc (talvez dê para arrumar via template).
A geração do exemplo de resposta também não está muito flexível, pelo que vi,
mas não parece ser um problema tão grande por enquanto.

Agora, escrever JSON na mão é uma droga. Sempre deixo sem querer uma "," no final
de um elemento e ele dá um pau louco que não fala onde está o erro. Acho que
se formos mesmo usar isso, vou escrever em Python (que permite sobrar ","),
importar e gerar o JSON, já que deve dar para traduzir de um para outro com 1
linha de código.

Quoting Andres MRM (2015-02-14 16:04:37)
> 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