[Gastosabertos-dev] Doc API

Segunda Março 9 00:23:11 UTC 2015

As páginas estão sendo compiladas no CircleCI, veja o
circle.yml. Depois de compilado é copiado para o servidor.
Veja também o fabfile.

Abs,
E.

On 08/03/2015 21:18, Andres MRM wrote:
> 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
> _______________________________________________
> Gastosabertos-dev mailing list
> Gastosabertos-dev em lists.okfn.org
> https://lists.okfn.org/mailman/listinfo/gastosabertos-dev