Adicionando pagina de documentação /docs #101

CarlosZiegler · 2020-07-21T09:23:04Z

Ola, aqui esta uma proposta para documentação com swagger, de acordo com a issue #14 .

Criado pagina /docs
Incluido arquivo Json da documentacao, na pasta /docs
Incluido na root um arquivo de css para o estilo da pagina
Criado arquivo /pages/_app.js para importar folha de estilo para pagina docs
Add no package.json swagger-ui-react

Segue alguns screenshots da pagina docs:

OBS: Rota DD esta retornando erro.

vercel · 2020-07-21T09:23:08Z

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/brasilapi/brasilapi/1yoepu146
✅ Preview: https://brasilapi-git-fork-carlosziegler-master.brasilapi.vercel.app

CarlosZiegler · 2020-07-21T09:46:50Z

Rota DDD nao esta funcionando corretamente, acredito que por isso nao esta fazendo o deploy.

wesleyburlani · 2020-07-21T12:56:35Z

Olá Carlos, estava vendo o projeto aqui e, apesar do arquivo [ddd].js ter um comentário especificando um exemplo de rota como sendo /api/cities/v1/ddd/21 , os testes do projeto apontam para a rota /api/ddd/v1/{ddd}, que seria a rota utilizada. De qualquer modo, a rota de DDD não está funcionando mesmo, usando a rota /api/ddd/v1/{ddd} o retorno é "502: BAD_GATEWAY, NO_RESPONSE_FROM_FUNCTION".

CarlosZiegler · 2020-07-21T13:04:48Z

Ola Wesley, vou modificar meu Pr aqui, valeu o toque .... E sim nao ta rodando mesmo... estranho ...

lucianopf · 2020-07-29T18:06:15Z

Mestre @CarlosZiegler primeiamente obrigado pelo PR! 🚀

Tenho 2 pontos de atenção aqui:
1 - Vc ta adicionando um arquivo yarn.lock sendo que na real a gnt usa package-lock, eu removeria o yarn do PR e manteria apenas o package-lock 👀

2 - A build ta dando erro , eu até mandei rebuildar pra testar mas continua dando problema 😢

15:03:49.432 | > Build error occurred
-- | --
15:03:49.434 | ReferenceError: window is not defined
15:03:49.434 | at Object.<anonymous> (/vercel/1bf7104b/node_modules/swagger-ui-react/swagger-ui.js:1:208)
15:03:49.434 | at Module._compile (internal/modules/cjs/loader.js:1156:30)
15:03:49.434 | at Object.Module._extensions..js (internal/modules/cjs/loader.js:1176:10)
15:03:49.434 | at Module.load (internal/modules/cjs/loader.js:1000:32)
15:03:49.434 | at Function.Module._load (internal/modules/cjs/loader.js:899:14)
15:03:49.434 | at Module.require (internal/modules/cjs/loader.js:1042:19)
15:03:49.434 | at require (internal/modules/cjs/helpers.js:77:18)
15:03:49.434 | at Object.<anonymous> (/vercel/1bf7104b/node_modules/swagger-ui-react/index.js:37:41)
15:03:49.434 | at Module._compile (internal/modules/cjs/loader.js:1156:30)
15:03:49.434 | at Object.Module._extensions..js (internal/modules/cjs/loader.js:1176:10)
15:03:49.457 | error Command failed with exit code 1.
15:03:49.458 | info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
15:03:49.468 | Error: Command "yarn run build" exited with 1
15:03:51.617 | Done with "package.json"

otaciliolacerda · 2020-07-30T09:20:59Z

Oi @CarlosZiegler, parabéns pela iniciativa. Gostaria de elaborar um pouco mais no ponto 2 dado pelo @lucianopf:

Isso parece ser um problema com SSR (server side rendering). Pela mensagem de erro parece que há uma tentativa de renderizar o component <SwaggerUI /> no servidor (por isso o window not defined). Apesar de não ter uma solução definitiva há uma discussão em andamento em swagger-ui/issues/6136

EDIT: Sendo o swagger um arquivo de documentação não seria mais interessante usar YAML? Acho que ficaria mais legível. O que você acha?

RodriAndreotti · 2020-07-30T15:30:06Z

Senhores, permitem que eu sugira uma alternativa ao SwaggerUI?
Sei que é a ferramenta mais usada hoje para documentação, mas eu gostei bastante de um projeto OpenSource de documentação chamado ReDoc, no meu ver ele tem até uma estética um pouco mais refinada que o Swagger UI.

Talvez, se a lib estiver dando dor de cabeça para publicar, possa ser uma alternativa.

Seguem links:
Repositório
Preview

CarlosZiegler · 2020-08-03T18:21:43Z

Opa, eu estava até o pescoço semana passada, essa semana vou dar uma olhadinha, mas bora implementar isso aí @RodriAndreotti que quero aprender a usar também hahah..

RodriAndreotti · 2020-08-03T21:12:22Z

Opa, eu estava até o pescoço semana passada, essa semana vou dar uma olhadinha, mas bora implementar isso aí @RodriAndreotti que quero aprender a usar também hahah..

Cara, se eu te falar que o negócio é fácil demais para implementar vc acredita?
É só baixar o repositório mesmo, e jogar o arquivo.json exportado do swagger-editor apontando para ele.
Se quiser tentar, para eu não atravessar seu PR, pode fazer ai, e se precisar de ajuda é só dar um toque.

Mas eu implementei nesse link aqui: https://neoedu.com.br/api-doc, caso queira dar uma olhada.

CarlosZiegler · 2020-08-04T09:19:32Z

@RodriAndreotti Sensacional esse REDOC, muito mais simples de implementar. Eu tomei a liberdade de pegar seu código do json e salvar aqui como exemplo para futuras implementações, pode ser? Estava dando um conflito de versão do lodash, eu arrumei no meu repo e mandei novamente. @lucianopf também exclui o arquivo yarn.lock, passou batido mesmo, bom que nas próximas eu me atento a isso. @otaciliolacerda Da uma olhada no que o @RodriAndreotti comentou, a implementação fica mais simples, pelo menos eu achei :) . @RodriAndreotti da uma olhada no meu PR e se tiver algo a arrumar, tome frente ai !!!!

RodriAndreotti · 2020-08-04T13:11:31Z

@RodriAndreotti Sensacional esse REDOC, muito mais simples de implementar. Eu tomei a liberdade de pegar seu código do json e salvar aqui como exemplo para futuras implementações, pode ser? Estava dando um conflito de versão do lodash, eu arrumei no meu repo e mandei novamente. @lucianopf também exclui o arquivo yarn.lock, passou batido mesmo, bom que nas próximas eu me atento a isso. @otaciliolacerda Da uma olhada no que o @RodriAndreotti comentou, a implementação fica mais simples, pelo menos eu achei :) . @RodriAndreotti da uma olhada no meu PR e se tiver algo a arrumar, tome frente ai !!!!

Cara, de minha parte, não há problema nenhum em usar o meu json, só peço para não publicar ele, pois não é de uma API pública, é do sistema da empresa que trabalho, porém o próprio site do redoc tem um json tbm para uso, caso queira disponibilizar publicamente ;-)

Com relação ao PR, vou dar uma olhada mais tarde, eu queria pegar algo para desenvolver aqui tbm, mas estou tão corrido por esses dias que é capaz de eu pegar algo e terminarem antes de mim... kkk

RodriAndreotti · 2020-08-04T13:49:23Z

pages/api-doc/index.js

+import { RedocStandalone } from 'redoc';
+import Documentation from './doc.json'
+
+export default function index2() {


Neste caso não seria melhor usar só index() para o nome da função?

Sim @RodriAndreotti, arrumei ja, e sobre o arquivo, nao vou publicar nao, seria apenas para consulta mesmo, achei bem interessante e completo para estudos.

Pode usar sim cara, sem problema, incluso, para gerar esse json eu usei um serviço chamado apimatic (https://www.apimatic.io/), na versão grátis ele permite modelar um API só, mas é suficiente às vezes. Ele permite importar modelos de json, de curl etc, e gera os endpoints prontos para vc só ajustar a documentação, depois de pronto é só exportar o json no formato openapi e usar no redoc (eles até tem um portal de documentação também, mas gostei mais do redoc, justamente por ser hospedado em nosso servidor)

Que massa, muito aprendizado nesse PR, valew mesmo as dicas e sinta-se a vontade de corrigir o PR :)

Opa... bom que deu para aprender alguma coisa, qualquer coisa é só gritar ;-)

CarlosZiegler · 2020-08-04T20:26:22Z

Adicionando screenshots:

otaciliolacerda · 2020-08-05T07:23:23Z

package.json

    "next": "9.3.2",
    "react": "16.12.0",
-    "react-dom": "16.12.0"
+    "react-dom": "16.12.0",
+    "redoc": "^2.0.0-rc.35",


É ok utilizar versão alpha?

Cara, para ser sincero, eu acho que o dev não deve ter alterado os releases tags do repositório:
https://github.com/Redocly/redoc/tags
Pois todos estão como RC, mas com a experiência que tive, ele funciona sem problemas.

Vi que a versão anterior não suporta OpenAPI v3.

Eu estava fuçando o changelog dele aqui, e parece que o suporte básico rola desde 2017 já:
https://github.com/Redocly/redoc/blob/master/CHANGELOG.md#200-alpha1-2017-11-23
Não sei se faltou ele complementar algo nas especificações, mas, teoricamente teria suporte.

otaciliolacerda · 2020-08-05T07:24:39Z

pages/api-doc/index.js

@@ -0,0 +1,13 @@
+import React from 'react'
+import { RedocStandalone } from 'redoc';
+import Documentation from './doc.json'


Eu sugiro utilizar YAML para tornar mais legível.

Por incrível que pareça eu acho o json mais legível, mas é só questão de opinião mesmo :-p

O exemplo que coloquei usando yaml e OpenAPI v3 pode ser facilmente convertido para json. O exemplo corrige algumas coisas do json que peguei daqui.

Na realidade para o front não tem tanta diferença, acho que o redoc lê os dois sem problemas, vai da preferência de cada um mesmo, aliás, até o próprio swagger editor já consegue exportar como json, se quiser (incluso, convertendo de swagger 2 para openapi tbm)
Mas essas conversões automáticas nem sempre ficam 100%, então é legal dar uma revisada para garantir que está tudo certo.

Ola pessoal, então queria saber uma coisa, no modelo que usei eu pego o Json e aponto no spec do componente redoc, com o Yaml seria a mesma coisa?

Sim... a mesma coisa, pelo que sei ele lê os dois formatos, se vc pegar uma url de um yaml e jogar no demo online dele, é possível ver o funcionamento:
https://redocly.github.io/redoc/

otaciliolacerda · 2020-08-05T07:25:41Z

pages/api-doc/doc.json

+  "swagger": "2.0",
+  "info": {
+    "description": "Documentacao do Brasil API",
+    "version": "1.0.5",


Não seria 1.0.0 (versão inicial)?

Ja corrigi, valeu mesmo!!!

otaciliolacerda · 2020-08-05T07:26:14Z

pages/api-doc/doc.json

@@ -0,0 +1,127 @@
+{
+  "swagger": "2.0",


Poderíamos utilizar a OpenAPI v3

Concordo, se existe uma especificação um pouco mais recente, é sempre bom trabalhar para manter a compatibilidade por mais tempo.

Ja alterei também, de acordo com o Yaml do @otacilio eu gerei um json, e atualizei o doc.json.

otaciliolacerda · 2020-08-05T07:54:22Z

Peguei o JSON desse PR e converti para utilizar v3 e YAML: Exemplo

Também tive que modificar alguns campos pois não passavam na validação do swagger editor. Talvez seja a diferença da v2 para v3.

Para ter algo visual, basta copiar & colar o conteúdo do yaml no swagger editor

CarlosZiegler · 2020-08-05T14:10:22Z

@otaciliolacerda , converti seu documento Yaml para Json e coloquei no PR, pois achei mais simples de implementar. Da uma olhada se esta tudo OK. E obrigado pela ajuda, com a ajuda de vocês ficou muito bom e o melhor eu aprendi muito. Realmente muito obrigado a vocês dois. Se tiver algo errado por favor me corrijam, tomem frente no PR, melhor que contribuir é aprender! hahah

lucianopf · 2020-08-10T20:31:20Z

Dúvida, a ideia é a rota ser /docs ou /api-doc mesmo? 🤔

No momento um deploy testavel ta aqui https://brasilapi-ls5vpzy2k.vercel.app/api-doc#tag/CEP! ^^

RodriAndreotti · 2020-08-10T22:56:42Z

Dúvida, a ideia é a rota ser /docs ou /api-doc mesmo? 🤔

No momento um deploy testavel ta aqui https://brasilapi-ls5vpzy2k.vercel.app/api-doc#tag/CEP! ^^

Bom, não sou o proprietário do PR, mas me parece melhor só /docs
Ele deve ter usado a mesma rota que usei no exemplo que mandei a ele, mas meu cenário era um pouco diferente... rs

CarlosZiegler · 2020-08-11T04:46:04Z

Bom dia, @lucianopf ja fiz a alteração para /docs. Realmente estava me baseando no que o @RodriAndreotti falou.

lucianopf · 2020-11-01T20:05:23Z

package.json

@@ -7,11 +7,15 @@
    "axios": "0.19.2",
    "cep-promise": "3.0.9",
    "cidades-promise": "^1.2.3",
-    "lodash": "^4.17.15",
+    "core-js": "^3.6.5",


Um ponto que não é um block pra esse PR é tentar deixar as versões fixadas no package.json pra evitar bumps considerados minors de dependências externas que podem quebrar o comportamento que esperamos.

murilohns

Cara ficou muito bom seu PR, o único ponto de atenção é que a rota de DDD está errada, mesmo que essa rota não esteja funcionando =[

murilohns · 2020-12-10T16:24:34Z

pages/docs/doc.json

+        }
+      }
+    },
+    "/cities/v1/ddd/{ddd}": {


Apesar dessa rota não estar funcionando, o endpoint correto é ddd/v1/{ddd}

Ola @murilohns . Eu ja resolvi isso pelo git mesmo, depois confere se atualizou ai ....

vercel · 2020-12-10T16:38:00Z

@CarlosZiegler is attempting to deploy a commit to the BrasilAPI Team on Vercel.

A member of the Team first needs to authorize it.

murilohns · 2020-12-10T17:53:42Z

Fui ajeitar a branch pro merge e acabei fechando o PR e tirando os commits sem querer, mas não precisa se desesperar não @CarlosZiegler, eu já to desesperado por nós dois!

Jaja corrijo isso :D

CarlosZiegler · 2020-12-10T19:28:20Z

Mas nem eh sexta feira ainda... hahaha

vercel bot had a problem deploying to Preview July 21, 2020 09:23 Failure

vercel bot had a problem deploying to Preview July 21, 2020 09:36 Failure

vercel bot had a problem deploying to Preview July 21, 2020 09:40 Failure

vercel bot had a problem deploying to Preview July 21, 2020 13:13 Failure

otaciliolacerda mentioned this pull request Jul 26, 2020

REST API versioning #102

Closed

vercel bot had a problem deploying to Preview July 29, 2020 18:02 Failure

lucianopf assigned CarlosZiegler Jul 29, 2020

lucianopf self-requested a review July 29, 2020 18:06

lucianopf added enhancement New feature or request documentation Improvements or additions to documentation labels Jul 29, 2020

vercel bot deployed to Preview August 4, 2020 08:14 View deployment

vercel bot deployed to Preview August 4, 2020 08:18 View deployment

RodriAndreotti mentioned this pull request Aug 4, 2020

Design + Marketing + layout #83

Closed

RodriAndreotti reviewed Aug 4, 2020

View reviewed changes

vercel bot deployed to Preview August 4, 2020 14:22 View deployment

otaciliolacerda reviewed Aug 5, 2020

View reviewed changes

vercel bot deployed to Preview August 5, 2020 14:01 View deployment

vercel bot deployed to Preview August 5, 2020 14:08 View deployment

vercel bot deployed to Preview August 11, 2020 04:43 View deployment

williamtorres1 approved these changes Oct 20, 2020

View reviewed changes

lucianopf approved these changes Nov 1, 2020

View reviewed changes

murilohns requested changes Dec 10, 2020

View reviewed changes

murilohns approved these changes Dec 10, 2020

View reviewed changes

murilohns closed this Dec 10, 2020

murilohns force-pushed the master branch from 8b8668e to 97039d2 Compare December 10, 2020 17:41

murilohns mentioned this pull request Dec 10, 2020

Adicionando página de documentação /docs #171

Merged

Adicionando pagina de documentação /docs #101

Adicionando pagina de documentação /docs #101

Conversation

CarlosZiegler commented Jul 21, 2020 • edited

vercel bot commented Jul 21, 2020 • edited

CarlosZiegler commented Jul 21, 2020

wesleyburlani commented Jul 21, 2020

CarlosZiegler commented Jul 21, 2020

lucianopf commented Jul 29, 2020

otaciliolacerda commented Jul 30, 2020 • edited

RodriAndreotti commented Jul 30, 2020

CarlosZiegler commented Aug 3, 2020

RodriAndreotti commented Aug 3, 2020

CarlosZiegler commented Aug 4, 2020

RodriAndreotti commented Aug 4, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

CarlosZiegler commented Aug 4, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

otaciliolacerda commented Aug 5, 2020

CarlosZiegler commented Aug 5, 2020

lucianopf commented Aug 10, 2020

RodriAndreotti commented Aug 10, 2020

CarlosZiegler commented Aug 11, 2020

Choose a reason for hiding this comment

murilohns left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vercel bot commented Dec 10, 2020

murilohns commented Dec 10, 2020

CarlosZiegler commented Dec 10, 2020

CarlosZiegler commented Jul 21, 2020 •

edited

vercel bot commented Jul 21, 2020 •

edited

otaciliolacerda commented Jul 30, 2020 •

edited