Como o Postman Documenter, mas para insônia! Com esta ferramenta você pode gerar lindas páginas de documentação de API usando seu arquivo de exportação do Insomnia.
Demonstração: https://insodoc.github.io/insomnia-documenter/
Tutorial e vídeo de demonstração: https://www.youtube.com/watch?v=pq2u3FqVVy8
npx
O Insomnia Documenter oferece uma ferramenta CLI para facilitar a configuração de uma página de documentação. Você pode usá-lo de duas maneiras.
npx
npx insomnia-documenter --config /path/to/insomnia/config.json
npm i -g insomnia-documenter
insomnia-documenter --config /path/to/insomnia/config.json
Options:
-c, --config <location> Location of the exported Insomnia JSON config.
-l, --logo <location> Project logo location (48x48px PNG).
-f, --favicon <location> Project favicon location (ICO).
-o, --output <location> Where to save the file (defaults to current working directory).
-h, --help output usage information
Alternativamente, você pode começar a usar o Insomnia Documenter baixando um arquivo de lançamento do GitHub e adicionando seu arquivo de exportação insomnia.json
ao diretório raiz do seu site.
Atualizar a API é super simples! Como o Insomnia Documenter é um aplicativo da web plug-and-play, você pode simplesmente substituir seu insomnia.json
pelo novo arquivo JSON exportado. Apenas certifique-se de que se chama insomnia.json
.
O mesmo se aplica ao logotipo ( logo.png
) e ao favicon ( favicon.ico
).
Talvez você queira documentar várias APIs no mesmo domínio? Talvez você queira hospedar sua página de documentação nas páginas do GitHub? Neste (em muitos outros casos), você precisará especificar qual é o caminho raiz. Para fazer isso, você deve abrir index.html
e substituir a seguinte linha:
< div id =" app " > </ div >
com algo assim:
< div id =" app " data-root =" /path/to/docs " > </ div >
Nesse caso, o aplicativo irá pegar o arquivo insomnia.json
do diretório /path/to/docs
. Isso lhe dá mais flexibilidade sobre como você deseja manter sua página de documentação (por exemplo, você pode armazenar o arquivo de exportação em algum lugar diferente do diretório raiz da página da web). Você NÃO deve colocar uma barra final na propriedade data-root
.
Observe que a configuração deste atributo não afetará o favicon e o logotipo da página. Eles ainda serão carregados do mesmo diretório onde está index.html
.
Abrir o arquivo index.html
não carregará em 99,9% dos casos porque é assim que a busca funciona. Para visualizar a página localmente, você pode usar uma ferramenta como zeit/serve:
npx serve
A página estará disponível em http://localhost:5000.
devhammed criou um plugin incrível para o Insomnia que permite gerar uma página de documentação diretamente da interface do Insomnia. Obtenha o plug-in (npm - github)
Por favor, consulte o documento Changelog.
A ferramenta CLI é um miniaplicativo Commander, enquanto o frontend em si é um aplicativo Svelte. Este projeto ainda está em beta, o que significa que possui bugs e pode ser melhorado aqui e ali. A contribuição é muito bem-vinda :)
Clone o repositório:
git clone [email protected]:jozsefsallai/insomnia-documenter.git
cd insomnia-documenter
Instale as dependências:
npm install
Copie o arquivo de exportação de demonstração do Insomnia:
cp docs/insomnia.json public/insomnia.json
Execute uma compilação de desenvolvimento com recarga dinâmica:
npm run dev
Crie uma versão de produção:
npm run build
Linting:
npm run lint
Teste:
npm run test
MIT.
Nota: este projeto não é afiliado a Kong e/ou Insomnia.
Disponível como parte da assinatura Tidelift
Os mantenedores do Insomnia Documenter e milhares de outros pacotes estão trabalhando com o Tidelift para fornecer suporte comercial e manutenção para as dependências de código aberto que você usa para construir seus aplicativos. Economize tempo, reduza riscos e melhore a integridade do código, pagando aos mantenedores pelas dependências exatas que você usa. Saber mais.