Conversão de especificação Swagger JSON em documentação HTML

88

Para algumas APIs REST escritas em PHP, fui solicitado a criar documentação Swagger e, como não conhecia nenhuma maneira fácil de adicionar anotações a essas APIs existentes e criar tal documentação, usei este editor para gerar algumas por agora.

Salvei os arquivos JSON e YAML criados usando esse editor e agora preciso criar a documentação interativa final do Swagger (esta declaração pode parecer ingênua e vaga).

Alguém pode me dizer como posso converter o arquivo de especificação Swagger JSON em documentação real do Swagger?

Estou na plataforma Windows e não conheço nada sobre o Ant / Maven.

yaml swagger swagger-php Salil
fonte
eu tentei [ github.com/wordnik/swagger-ui](Swagger UI), mas não está renderizando meu json. o único aviso mostrado é "Esta API está usando uma versão obsoleta do Swagger! Consulte github.com/wordnik/swagger-core/wiki para obter mais informações".
Salil

Respostas:

43

Não fiquei satisfeito swagger-codegenquando estava procurando uma ferramenta para fazer isso, então escrevi minha própria. Dê uma olhada no bootprint-swagger

O objetivo principal em comparação com swagger-codegené fornecer uma configuração fácil (embora você precise do nodejs). E deve ser fácil de se adaptar styling e modelos para suas próprias necessidades, que é uma funcionalidade central do bootprint -project

Nils Knappmeier
fonte
9
Aviso: em 11/2016, o autor de bootprint-swagger aparentemente abandonou o projeto. swagger-codegen ainda é bem suportado.
Brent Matzelle
22
Eu sou o autor e o texto diz: "Lamento dizer que não poderei desenvolver novos recursos para este projeto em um futuro próximo. Mas: Provavelmente serei capaz de discutir e mesclar solicitações de pull, e publicar novas versões. " Você pode chamar isso de abandonado, eu chamaria de "em espera". Também convido quem estiver interessado em contribuir com o projeto.
Nils Knappmeier
1
Encontrado que spectaclegera uma documentação muito mais bonita do swagger JSON
eternalthinker
Depois de muita luta, achei esta ferramenta muito útil: api-html
Asfandiyar Khan
57

Tente usar redoc-cli .

Eu estava usando bootprint-AbraAPI pelo qual eu estava gerando um monte de arquivos ( bundle.js, bundle.js.map, index.html, main.csse main.css.map) e, em seguida, você pode convertê-lo em um único .htmlarquivo usando html-inline para gerar um simples index.htmlarquivo.

Então eu achei redoc-cli muito fácil de usar e a saída é realmente incrível, um único e bonito arquivo index.html .

Instalação :

npm install -g redoc-cli

Uso :

redoc-cli bundle -o index.html swagger.json
Vikasdeep Singh
fonte
8
Esta ferramenta faz realmente o resultado mais bonito de todas as ferramentas mencionadas.
Jakub Moravec
1
Este é de longe o melhor, e como o estamos construindo para desenvolvedores que usam desktops, o tamanho da saída não é um problema.
milosmns
3
Usar o nome do executável direto nem sempre funciona, a execução por npx redoc-cli ...é mais confiável.
Gatinho Agachado de
2
Saída muito bonita. Obrigado pela sugestão.
Sahil Jain
1
Esta é uma ferramenta incrível !! Obrigada Vikas profundamente pela maravilhosa sugestão mano !! Definitivamente muito melhor e menos desajeitado do que bootstrap-openapi!
Chaturvedi Saurabh
19

Dê uma olhada em um estilo bonito

Tem

  1. Semelhante ao painel direito do Swagger-Editor
  2. Pesquisa / Filtro
  3. Schema Folding
  4. Feedback ao vivo
  5. Saída como um único arquivo html

Eu estava olhando para o Editor Swagger e pensei que ele poderia exportar o painel de visualização, mas descobri que não pode. Então, escrevi minha própria versão disso.

Divulgação completa: eu sou o autor da ferramenta.

TLJ
fonte
1
Eu descobri que o pretty-swag é uma ferramenta simples e ideal, com CLI e pontos de entrada de API apropriados. Minha única reclamação (e aquela que me forçou a lidar com a complexidade do swagger-ui) foi a falha em lidar corretamente com a composição / extensão de objetos. Qualquer uso de allOfno documento produz undefined, mesmo nos cenários mais simples ("mesclar" um único objeto, equivalente a não usar de allOftodo).
HonoredMule 01 de
3
Acabei de lançar o allOfrecurso para você. Confira.
TLJ
2
Não parece ser compatível com Swagger / OpenAPI V3
SeinopSys
18

Tudo estava muito difícil ou mal documentado, então resolvi isso com um script simples swagger-yaml-to-html.py , que funciona assim

python swagger-yaml-to-html.py < /path/to/api.yaml > doc.html

Isso é para YAML, mas modificá-lo para funcionar com JSON também é trivial.

Oseiskar
fonte
Isso é ouro puro!
zemirco
16

Veja o projeto swagger-api / swagger-codegen no GitHub; o projeto README mostra como usá-lo para gerar HTML estático. Consulte Gerando documentação de API de html estática .

Se você deseja visualizar o swagger.json, pode instalar a IU do Swagger e executá-lo. Basta implantá-lo em um servidor da web (a pasta dist depois de clonar o repo do GitHub) e visualizar a IU do Swagger em seu navegador. É um aplicativo JavaScript.

djb
fonte
Obrigado. Meu problema era que o swagger-ui não estava aceitando as especificações 2.0. No entanto, essa parece ser a resposta mais simples, então vou aceitá-la (por enquanto).
Salil de
As ferramentas Swagger ainda estão evoluindo para 2.0. No entanto, descobri que a IU do Swagger funciona para meus arquivos 2.0 que começam com "swagger": "2.0",
djb
Além disso, a partir do Editor Swagger, você pode exportar a especificação JSON (não como YAML, mas como JSON) e a IU do Swagger deve ser capaz de ler isso. (Observação: o swagger.json deve estar no mesmo host / porta que o aplicativo Swagger UI, ou você deve ativar o CORS; consulte o README.md no Editor Swagger no GitHub
djb
14

Passei muito tempo e tentei várias soluções diferentes - no final, fiz desta forma:

<html>
    <head>    
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/swagger-ui.css">
        <script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
        <script>

            function render() {
                var ui = SwaggerUIBundle({
                    url:  `path/to/my/swagger.yaml`,
                    dom_id: '#swagger-ui',
                    presets: [
                        SwaggerUIBundle.presets.apis,
                        SwaggerUIBundle.SwaggerUIStandalonePreset
                    ]
                });
            }

        </script>
    </head>

    <body onload="render()">
        <div id="swagger-ui"></div>
    </body>
</html>

Você só precisa ter path / to / my / swagger.yaml servido no mesmo local.
(ou use cabeçalhos CORS)

Kris Randall
fonte
Incrível, obrigado! Eu usei <link rel = "stylesheet" href = " petstore.swagger.io/swagger-ui.css "> <script src = " petstore.swagger.io/swagger-ui-bundle.js "></script >
Erando
1
Achei que essa é a melhor solução, sem instalação de nada!
KurioZ7
Extremamente útil. Você economizou muito tempo.
kalpesh khule
7

Você também pode baixar o swagger ui em: https://github.com/swagger-api/swagger-ui , pegue a pasta dist, modifique index.html: altere o construtor

const ui = SwaggerUIBundle({
    url: ...,

para dentro

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

agora a pasta dist contém tudo o que você precisa e pode ser distribuída como está

user1928596
fonte
2

Dê uma olhada neste link: http://zircote.com/swagger-php/installation.html

  1. Baixe o arquivo phar https://github.com/zircote/swagger-php/blob/master/swagger.phar
  2. Instalar o Composer https://getcomposer.org/download/
  3. Faça composer.json
  4. Clone swagger-php / library
  5. Clone swagger-ui / library
  6. Faça classes de recursos e modelos php para a API
  7. Execute o arquivo PHP para gerar o json
  8. Forneça o caminho de json em api-doc.json
  9. Forneça o caminho de api-doc.json em index.php dentro da pasta swagger-ui dist

Se precisar de outra ajuda, sinta-se à vontade para perguntar.

Syed Raza Mehdi
fonte
1
Existe um editor online (além do editor de arrogância) que pode gerar isso para mim? Não quero anotar minhas APIs de PHP se houver uma maneira mais simples. O problema, descobri, é que o editor swagger gera a especificação swagger v2.0, e o swagger-ui não cuida disso no momento.
Salil
@Salil tudo que eu sei é que o swagger oferece seu próprio editor on-line, ou seja, editor.swagger.wordnik.com Não conheço nenhum outro editor on-line, se você encontrar algum, compartilhe conosco, obrigado :)
Syed Raza Mehdi
2

Existe um pequeno programa Java que gera documentos (adoc ou md) a partir de um arquivo yaml.

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
        .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .withSwaggerMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .withOutputLanguage(Language.DE)
        .build();

Swagger2MarkupConverter builder = Swagger2MarkupConverter.from(yamlFileAsString).withConfig(config).build();
return builder.toFileWithoutExtension(outFile);

Infelizmente, ele só oferece suporte a OpenAPI 2.0, mas não a OpenAPI 3.0 .

Erando
fonte
2

Para Swagger API 3.0, gerar código de cliente Html2 a partir do Editor Swagger online funciona muito bem para mim!

Kumar S
fonte
1

Eu encontrei esta ferramenta chamada api-html muito útil. Ele está gerando uma interface de usuário em html5 incrível com muitas possibilidades.

Existem opções para gerar online ou por meio da ferramenta CLI .

Aqui está um link para a versão de demonstração em "api-html": pets-demo

Asfandiyar Khan
fonte