Converting Swagger specification JSON to HTML documentation

Question

For some REST APIs written in PHP  I was asked to create Swagger documentation  and since I was not aware of any easy way of adding annotations to those existing APIs and create such a documentation  I used this editor to generate some for now   I saved the JSON and YAML files created using that editor  and now I need to create the final interactive Swagger documentation  this statement might sound naive and vague    Can someone please let me know how I can convert the Swagger JSON specification file to actual Swagger documentation    I am on the Windows platform and do not know anything about Ant Maven

User · Answer

Everything was too difficult or badly documented so I solved this with a simple script swagger-yaml-to-html.py, which works like this

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

This is for YAML but modifying it to work with JSON is also trivial.

User · Answer

Check out pretty-swag   It has   Similar looking as Swagger-Editor s right panel Search   Filter Schema Folding Live Feedback Output as a single html file   I was looking at Swagger Editor and thought it could export the preview pane but turned out it cannot  So I wrote my own version of it   Full Disclosure  I am the author of the tool

User · Answer

Give a look at this link   http   zircote com swagger-php installation html   Download phar file https   github com zircote swagger-php blob master swagger phar  Install Composer https   getcomposer org download  Make composer json Clone swagger-php library Clone swagger-ui library Make Resource and Model php classes for the API  Execute the PHP file to generate the json Give path of json in api-doc json Give path of api-doc json in index php inside swagger-ui dist folder    If you need another help please feel free to ask

User · Answer

For Swagger API 3 0  generating Html2 client code  from online Swagger Editor works great for me

User · Answer

I was not satisfied with swagger-codegen when I was looking for a tool to do this  so I wrote my own  Have a look at bootprint-swagger  The main goal compared to swagger-codegen is to provide an easy setup  though you ll need nodejs   And it should be easy to adapt styling and templates to your own needs  which is a core functionality of the bootprint-project

User · Answer

Try to use redoc-cli   I was using bootprint-openapi by which I was generating a bunch of files  bundle js  bundle js map  index html  main css and main css map  and then you can convert it into a single  html file using html-inline to generate a simple index html file    Then I found redoc-cli very easy to to use and output is really-2 awesome  a single and beautiful index html file   Installation   npm install -g redoc-cli   Usage   redoc-cli bundle -o index html swagger json

User · Answer

You can also download swagger ui from  https   github com swagger-api swagger-ui  take the dist folder  modify index html  change the constructor   const ui   SwaggerUIBundle       url         into  const ui   SwaggerUIBundle       spec  YOUR JSON    now the dist folder contains all what you need and can be distributed as is

User · Answer

There s a small Java program which generates docs  adoc or md  from a yaml file   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     Unfortunately it only supports OpenAPI 2 0 but not OpenAPI 3 0

User · Answer

See the swagger-api swagger-codegen project on GitHub   the project README shows how to use it to generate static HTML  See Generating static html api documentation   If you want to view the swagger json you can install the Swagger UI and run it  You just deploy it on a web server  the dist folder after you clone the repo from GitHub  and view the Swagger UI in your browser  It s a JavaScript app

User · Answer

I spent a lot of time and tried a lot of different solutions - in the end I did it this way     lt html gt       lt head gt               lt link rel  stylesheet  href  https   cdn jsdelivr net npm swagger-ui-dist 3 17 0 swagger-ui css  gt           lt script src    unpkg com swagger-ui-dist 3 swagger-ui-bundle js  gt  lt  script gt           lt script gt               function render                     var ui   SwaggerUIBundle                       url    path to my swagger yaml                       dom id    swagger-ui                       presets                            SwaggerUIBundle presets apis                          SwaggerUIBundle SwaggerUIStandalonePreset                                                                   lt  script gt       lt  head gt        lt body onload  render    gt           lt div id  swagger-ui  gt  lt  div gt       lt  body gt   lt  html gt    You just need to have path to my swagger yaml served from the same location   or use CORS headers

[yaml] Converting Swagger specification JSON to HTML documentation

Examples related to yaml

Examples related to swagger

Examples related to swagger-php