Documentaçao da API

[CarlosZiegler]

Ola, estava lendo sobre a API e fiquei pensando sobre a documentação da mesma. Segue os links que achei interessante.

• Swagger : https://swagger.io/
• Redoc : https://github.com/Redocly/redoc
• OpenAPi : https://www.openapis.org/
• API Blue Print : https://apiblueprint.org/
• Postman : https://learning.postman.com/docs/postman/api-documentation/documenting-your-api/

[sleao]

Achei bem interessante esse API Blueprint. Tirei uns minutos aqui pra testar como ficaria a implementação da documentação da API do CEP. Por enquanto só consegui visualizar usando o Apiary, que infelizmente é pago quando se trabalha com times. Existe algum lugar onde eu possa dar upload que facilite o desenvolvimento sem custar nada?

EDIT: Que não seja o GitHub, já que a ideia por trás da Blueprint é visualizar utilizando o feature de Markdown de um lado e Visualização da API do outro.

[CarlosZiegler]

Eu vi sobre o Swagger, mas nao encontrei material sobre implementar ele no Next.Js apenas no Express.

[filipedeschamps]

Show!!!!!

[pedroigorjs]

Achei bem interessante esse API Blueprint. Tirei uns minutos aqui pra testar como ficaria a implementação da documentação da API do CEP. Por enquanto só consegui visualizar usando o Apiary, que infelizmente é pago quando se trabalha com times. Existe algum lugar onde eu possa dar upload que facilite o desenvolvimento sem custar nada?

EDIT: Que não seja o GitHub, já que a ideia por trás da Blueprint é visualizar utilizando o feature de Markdown de um lado e Visualização da API do outro.

Eu gosto bastante do Blueprint, na aba de Tools há diversos renders e recomendo o Aglio, inclusive é possível levantar um mock direto da documentação com o Drakov além de testes automatizados utilizando a especificação dela com o Dredd, também é possível converter para outras especificações como o Swagger.

[ItaloSa]

É super importante ter uma documentação legal. É o que vai fazer com que as pessoas usem com mais facilidade a API. @filipedeschamps Já tem alguma ideia de qual soluçao de documentação que vai usar?

[RodrigoDornelles]

Acho interessante criar um repositório na organização para focar na documentação, podemos usar até o github pages para isso, porque algo comum na comunidade open source, a galera até buscar por um brasilapi.github.io

[allangrds]

Já mexi com o API Blueprint + Aglio, poderia ajudar nisso.

Exemplo da API Blueprint hosteada na Apiary: https://gamer1.docs.apiary.io/#reference/games/plataforms/criar-plataforma
Exemplo de projeto com API Blueprint + Apiary: https://github.com/allangrds/pagarme-payment-service-provider/tree/master/docs/src

Acredito que facilita deixar tudo por aqui. Acham que vale um repo novo ao invés de deixar aqui?

cc @lucianopf @matheusvellone

[allangrds]

#171

[murilohns]

O PR #171 já foi merged e criava a documentação: https://brasilapi.com.br/docs

Vou fechar essa issue.

@CarlosZiegler obrigado pela contribuição!