validator specification open example yaml swagger swagger-php

yaml - specification - Conversión de la especificación JSON de Swagger a documentación HTML



swagger validator (10)

Para algunas API REST escritas en PHP, se me pidió que creara la documentación de Swagger , y dado que no conocía ninguna forma fácil de agregar anotaciones a esas API existentes y crear dicha documentación, utilicé este editor para generar algo 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).

¿Puede alguien decirme cómo puedo convertir el archivo de especificación Swagger JSON a la documentación real de Swagger?

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

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. Instalar Composer https://getcomposer.org/download/
  3. Make composer.json
  4. Clonar swagger-php / library
  5. Clone swagger-ui / library
  6. Hacer clases de recursos y modelos de php 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.

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 .

Intenta usar redoc-cli .

Estaba usando bootprint-openapi mediante el cual estaba generando un montón de archivos ( bundle.js , bundle.js.map , index.html , main.css y main.css.map ) y luego puede convertirlo en uno solo .html archivo .html usando html-inline para generar un archivo index.html simple.

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

Instalación :

npm install -g redoc-cli

Uso :

redoc-cli bundle -o index.html swagger.json

Mira pretty-swag

Tiene

  1. Aspecto similar al panel derecho del Swagger-Editor
  2. Filtro de búsqueda
  3. Esquema Plegable
  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. Entonces escribí mi propia versión.

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

No estaba satisfecho con swagger-codegen cuando buscaba una herramienta para hacer esto, así que escribí el mío. Echa un vistazo a bootprint-swagger

El objetivo principal en comparación con swagger-codegen es 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 central del proyecto bootprint

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

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 ruta / to / my / swagger.yaml desde la misma ubicación.
(o use encabezados CORS)

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

Todo era demasiado difícil o estaba mal documentado, así que lo resolví 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.