[Gastosabertos-dev] Doc API

Domingo Março 8 23:19:20 UTC 2015

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
-------------- Próxima Parte ----------
Um anexo em HTML foi limpo...
URL: <http://lists.okfn.org/pipermail/gastosabertos-dev/attachments/20150308/58352a7c/attachment-0003.html>