[Gastosabertos-dev] Doc API

Sexta Março 20 13:14:55 UTC 2015

"Trombei" hoje com uma lib que me pareceu interessante:
https://pypi.python.org/pypi/flask-restplus/0.6.0
Mas especificamente isso:
http://flask-restplus.readthedocs.org/en/0.6.0/swaggerui.html
Para testar como fica basta dar um "pip install flask-restplus", jogar o
exemplo que ele mostra em um arquivo e rodar.
E aqui tem um exemplo mais completo:
https://github.com/noirbizarre/flask-restplus/blob/master/examples/todo.py

É uma interface Swagger, ela deixa brincar com a API na própria doc.
Parece que ele está usando as Docstrings direto na documentação também, o que
é bem prático. Aparentemente o tipo de validação de entradas é o mesmo que nós
já estamos usando.

Ou seja, me pareceu ter muitas vantagens.

Tendo dito isso, acho a interface do Swagger um pouco carregada num primeiro
momento. Mas depois de alguns minutos acho que já me acostumei.
Outra questão é que aparentemente não teríamos mais um "mega JsonHyperSchema"
com todos os URLs, formatos etc num mesmo arquivo (talvez dê para gerar isso
do Swagger, mas não sei...).
Porém, ele aparece estar gerando os Schemas de cada resposta automaticamente
na interface, o que é uma mão na roda...

A biblioteca é relativamente nova (meio do ano passado) e tocada por um cara,
mas tem commits recentes.

O que acham? Abrimos mão do "JsonHyperSchema" e usamos esse ai?

Quoting Edgar Zanella Alvarenga (2015-03-08 21:23:11)
> 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
> 
> _______________________________________________
> Gastosabertos-dev mailing list
> Gastosabertos-dev em lists.okfn.org
> https://lists.okfn.org/mailman/listinfo/gastosabertos-dev