Conversión de la especificación JSON de Swagger a documentación HTML

88

Para algunas API REST escritas en PHP, se me pidió que creara la documentación de Swagger , y como no conocía ninguna forma fácil de agregar anotaciones a esas API existentes y crear dicha documentación, usé este editor para generar algunas por ahora.

Guardé los archivos JSON y YAML creados con ese editor, y ahora necesito crear la documentación interactiva final de Swagger (esta declaración puede sonar ingenua y vaga).

¿Alguien puede decirme cómo puedo convertir el archivo de especificación Swagger JSON en la documentación real de Swagger?

Estoy en la plataforma Windows y no sé nada sobre Ant / Maven.

yaml swagger swagger-php Salil
fuente
Intenté [ github.com/wordnik/swagger-ui](Swagger UI) pero no muestra mi json. la única advertencia que se muestra es "¡Esta API está usando una versión obsoleta de Swagger! Consulta github.com/wordnik/swagger-core/wiki para obtener más información".
Salil

Respuestas:

43

No estaba satisfecho swagger-codegencuando estaba buscando una herramienta para hacer esto, así que escribí la mía propia. Eche un vistazo a bootprint-swagger

El objetivo principal en comparación con swagger-codegenes proporcionar una configuración fácil (aunque necesitará nodejs). Y debería ser fácil adaptar el estilo y las plantillas a sus propias necesidades, que es una funcionalidad básica del proyecto bootprint .

Nils Knappmeier
fuente
9
Advertencia: A partir del 11/2016, el autor de bootprint-swagger aparentemente abandonó el proyecto. swagger-codegen todavía está bien soportado.
Brent Matzelle
22
Soy el autor y el texto dice: "Lamento decir que no podré desarrollar nuevas funciones para este proyecto en un futuro cercano. Pero: probablemente podré discutir y fusionar solicitudes de extracción, y publicar nuevas versiones ". Podría llamarlo abandonado, yo lo llamaría "en espera". También invitaré a cualquiera que esté interesado en contribuir al proyecto.
Nils Knappmeier
1
Se encontró que spectaclegenera una documentación mucho más atractiva de swagger JSON
eternalthinker
Después de mucha lucha, encontré esta herramienta muy útil: api-html
Asfandiyar Khan
57

Intenta usar redoc-cli .

Yo estaba usando bootprint-API abierta por el cual yo estaba generando un montón de archivos ( bundle.js, bundle.js.map, index.html, main.cssy main.css.map) y luego se puede convertir en un solo .htmlarchivo usando html-inline para generar un sencilloindex.html archivo.

Luego encontré redoc-cli muy fácil de usar y la salida es realmente impresionante, un único y hermoso index.html archivo .

Instalación :

npm install -g redoc-cli

Uso :

redoc-cli bundle -o index.html swagger.json
Vikasdeep Singh
fuente
8
Esta herramienta hace realmente la salida más hermosa de todas las herramientas mencionadas.
Jakub Moravec
1
Este es el mejor de lejos en mi opinión, y dado que lo estamos creando para desarrolladores que usan computadoras de escritorio, el tamaño de salida no es un problema.
milosmns
3
El uso de un nombre ejecutable directo no siempre funciona, la ejecución por npx redoc-cli ...es más confiable.
Gatito
2
Salida muy bonita. Gracias por la sugerencia.
Sahil Jain
1
¡Esta es una herramienta increíble! Gracias Vikas profundamente por la maravillosa sugerencia hermano !! ¡Definitivamente mucho mejor y menos torpe que bootstrap-openapi!
Chaturvedi Saurabh
19

Echa un vistazo a pretty-swag

Tiene

  1. Aspecto similar al panel derecho de Swagger-Editor
  2. Filtro de búsqueda
  3. Plegado de esquema
  4. Comentarios en vivo
  5. Salida como un solo archivo html

Estaba mirando Swagger Editor y pensé que podría exportar el panel de vista previa, pero resultó que no puede. Así que escribí mi propia versión.

Divulgación completa: soy el autor de la herramienta.

TLJ
fuente
1
He descubierto que pretty-swag es una herramienta sencilla e ideal, con puntos de entrada CLI y API apropiados. Mi única queja (y la que me obligó a lidiar con la complejidad de swagger-ui en su lugar) fue su incapacidad para manejar correctamente la composición / extensión del objeto. Cualquier uso de allOfen el documento produce undefined, incluso en los escenarios más simples ("fusionar" un solo objeto, equivalente a no usar allOfnada).
HonoredMule
3
Acabo de lanzar una allOffunción para ti. Echale un vistazo.
TLJ
2
No parece ser compatible con Swagger / OpenAPI V3
SeinopSys
18

Todo era demasiado difícil o estaba mal documentado, así que resolví esto con un simple script swagger-yaml-to-html.py , que funciona así

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

Esto es para YAML, pero modificarlo para que funcione con JSON también es trivial.

oseiskar
fuente
¡Esto es oro puro!
zemirco
16

Vea el proyecto swagger-api / swagger-codegen en GitHub; el proyecto README muestra cómo usarlo para generar HTML estático. Consulte Generación de documentación de api HTML estática .

Si desea ver swagger.json, puede instalar la interfaz de usuario de Swagger y ejecutarla. Simplemente impleméntelo en un servidor web (la carpeta dist después de clonar el repositorio de GitHub) y vea la IU de Swagger en su navegador. Es una aplicación de JavaScript.

djb
fuente
Gracias. Mi problema era que el swagger-ui no aceptaba la especificación 2.0. Sin embargo, esta parece la respuesta más simple, así que la aceptaré (por ahora).
Salil
Las herramientas Swagger todavía están evolucionando para 2.0. Sin embargo, descubrí que la interfaz de usuario de Swagger funciona para mis archivos 2.0 que comienzan con "swagger": "2.0",
djb
Además, desde Swagger Editor, puede exportar la especificación JSON (no como YAML sino como JSON) y la interfaz de usuario de Swagger debería poder leer eso. (Nota: swagger.json debe estar en el mismo host / puerto que la aplicación Swagger UI, o debe habilitar CORS; consulte README.md en Swagger Editor en GitHub
djb
14

Pasé mucho tiempo y probé muchas soluciones diferentes; al final, lo hice de esta manera:

<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>

Solo necesita tener la ruta / a / mi / swagger.yaml desde la misma ubicación.
(o use encabezados CORS)

Kris Randall
fuente
¡Genial gracias! He usado <link rel = "stylesheet" href = " petstore.swagger.io/swagger-ui.css "> <script src = " petstore.swagger.io/swagger-ui-bundle.js "></script >
Erando
1
Encontré que esta es la mejor solución, ¡sin instalación de nada!
KurioZ7
Extramadamente útil. Ahorraste mucho tiempo.
kalpesh khule
7

También puede descargar swagger ui desde: https://github.com/swagger-api/swagger-ui , tomar la carpeta dist, modificar index.html: cambiar el constructor

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

dentro

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

ahora la carpeta dist contiene todo lo que necesita y se puede distribuir como está

user1928596
fuente
2

Eche un vistazo a este enlace: http://zircote.com/swagger-php/installation.html

  1. Descargue el archivo phar https://github.com/zircote/swagger-php/blob/master/swagger.phar
  2. Instale Composer https://getcomposer.org/download/
  3. Hacer composer.json
  4. Clonar swagger-php / biblioteca
  5. Clonar swagger-ui / biblioteca
  6. Crear clases php de modelo y recurso para la API
  7. Ejecute el archivo PHP para generar el json
  8. Dar ruta de json en api-doc.json
  9. Proporcione la ruta de api-doc.json en index.php dentro de la carpeta swagger-ui dist

Si necesita otra ayuda, no dude en preguntar.

Syed Raza Mehdi
fuente
1
¿Existe un editor en línea (que no sea swagger-editor) que pueda generar esto por mí? No quiero hacer anotaciones en mis API de PHP si hay una forma más sencilla. El problema, me he dado cuenta es que swagger-editor genera swagger spec v2.0, y swagger-ui no maneja eso a partir de ahora.
Salil
@Salil todo lo que sé es que swagger proporciona su propio editor en línea, es decir, editor.swagger.wordnik.com No tengo conocimiento de ningún otro editor en línea, si encuentra alguno, compártelo con nosotros, gracias :)
Syed Raza Mehdi
2

Hay un pequeño programa Java que genera documentos (adoc o md) a partir de un archivo 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);

Desafortunadamente, solo es compatible con OpenAPI 2.0 pero no con OpenAPI 3.0 .

Erando
fuente
2

Para Swagger API 3.0, ¡generar código de cliente Html2 desde Swagger Editor en línea funciona muy bien para mí!

Kumar S
fuente
1

Encontré esta herramienta llamada api-html muy útil. Está generando una interfaz de usuario html5 impresionante con muchas posibilidades.

Hay opciones para generar en línea o mediante la herramienta cli .

Aquí hay un enlace a la demostración basada en "api-html": pets-demo

Asfandiyar Khan
fuente