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

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

Semelhante ao painel direito do Swagger-Editor
Pesquisa / Filtro
Schema Folding
Feedback ao vivo
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/swagger-ui-dist@3.17.0/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

Baixe o arquivo phar https://github.com/zircote/swagger-php/blob/master/swagger.phar
Instalar o Composer https://getcomposer.org/download/
Faça composer.json
Clone swagger-php / library
Clone swagger-ui / library
Faça classes de recursos e modelos php para a API
Execute o arquivo PHP para gerar o json
Forneça o caminho de json em api-doc.json
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