Converting Swagger specification JSON to HTML documentation

Yaml Problem Overview

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.

Yaml Solutions

Solution 1 - Yaml

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

Solution 2 - Yaml

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

Solution 3 - Yaml

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.

Solution 4 - Yaml

I spent a lot of time and tried a lot of different solutions - in the end I did it this way :

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

You just need to have path/to/my/swagger.yaml served from the same location.
(or use CORS headers)

Solution 5 - Yaml

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.

Solution 6 - Yaml

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.

Solution 7 - Yaml

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

Solution 8 - Yaml

For Swagger API 3.0, generating Html2 client code from online Swagger Editor works great for me!

Solution 9 - Yaml

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.

Solution 10 - Yaml

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.

Solution 11 - Yaml

If you commit your JSON file in Gitlab, it will render it for you.

Content Type	Original Author	Original Content on Stackoverflow
Question	Salil	View Question on Stackoverflow
Solution 1 - Yaml	Vikasdeep Singh	View Answer on Stackoverflow
Solution 2 - Yaml	Nils Knappmeier	View Answer on Stackoverflow
Solution 3 - Yaml	oseiskar	View Answer on Stackoverflow
Solution 4 - Yaml	Kris Randall	View Answer on Stackoverflow
Solution 5 - Yaml	TLJ	View Answer on Stackoverflow
Solution 6 - Yaml	djb	View Answer on Stackoverflow
Solution 7 - Yaml	user1928596	View Answer on Stackoverflow
Solution 8 - Yaml	Kumar S	View Answer on Stackoverflow
Solution 9 - Yaml	Syed Raza Mehdi	View Answer on Stackoverflow
Solution 10 - Yaml	Erando	View Answer on Stackoverflow
Solution 11 - Yaml	trax	View Answer on Stackoverflow