[Gastosabertos-dev] Doc API

Segunda Março 9 00:18:57 UTC 2015

Então, no pandoc aqui do Arch Linux foi sem instalar nada extra. Mas pode ser
que no pandoc que está no servidor precise. O estranho é que não tinha um
pandoc instalado globalmente, então não sei qual está sendo usado. Mesmo
porque não achei o código do site no servidor, só o build.

Quoting Luiz Armesto (2015-03-08 20:19:20)
> Acho que tabelas não faziam parte do markdown originalmente e deve precisar de
> alguma extensão no pandoc para converter direito
> 
> 2015-03-08 19:31 GMT-03:00 Andres MRM <andres em inventati.org>:
> 
> 
>     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
>     _______________________________________________
>     Gastosabertos-dev mailing list
>     Gastosabertos-dev em lists.okfn.org
>     https://lists.okfn.org/mailman/listinfo/gastosabertos-dev
> 
> 
> 
> 
> --
> Luiz Armesto