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 annotating 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 "interactive" Swagger documentation from there.

Can someone please let me know how I can convert the Swagger JSON specification file to an actual Swagger documentation?

I am on the Windows platform and do not know anything about Ant/Maven.

i tried [https://github.com/wordnik/swagger-ui](Swagger UI) but it is not rendering my json. the only warning shown is "This API is using a deprecated version of Swagger! Please see http://github.com/wordnik/swagger-core/wiki for more info". — Salil, Sep 12 '14 at 07:29

Vikasdeep Singh · Answer 1 · 2023-05-17T01:26:31.547

111

Update May 17, 2023

Seems redoc-cli has been deprecated. so use https://www.npmjs.com/package/@redocly/cli instead. [Credit : @Dave]

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

edited May 17 '23 at 01:26

answered Jun 22 '18 at 07:45

Vikasdeep Singh

20,983
15
78
104

12

This tool makes really the most beautiful output of all tools mentioned. – Jakub Moravec Jul 16 '18 at 14:09
The generated all-in-one HTML file is quite big. So is the JS library dependency (~800KB) in the case that of live-rendering from custom HTML. Does anyone know how the size can be reduced? – aaronqli Dec 17 '18 at 06:02
1

This one is the best by far imo, and since we're building this for developers who are using desktops, the output size is a non-issue. – milosmns Jul 04 '19 at 14:09
4

Using direct executable name not always works, execution by `npx redoc-cli ...` is more dependable. – Crouching Kitten Aug 20 '19 at 10:18
1

wow. It took me under a minute to have all that doc in one file - on a Mac; is npm now built in? Thanks! – Josef Habr Jan 12 '22 at 12:54
How can I add Request body properties in Swagger YAML? – Sach Mar 17 '22 at 14:57
4

small update: `redoc-cli` now wants you to use the `build` option instead of `bundle`. – TheDiveO May 13 '22 at 07:15
3

Tried this and it told me it was deprecated, and to use https://www.npmjs.com/package/@redocly/cli instead. – Dave May 16 '23 at 09:48

score 48 · Accepted Answer · answered Jun 28 '15 at 06:25

48

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

answered Jun 28 '15 at 06:25

Nils Knappmeier

669
7
10

12

Warning: As of 11/2016 the author of bootprint-swagger apparently has abandoned the project. swagger-codegen is still well supported. – Brent Matzelle Nov 23 '16 at 21:02
26

I am the author and the text says: "I'm sorry to say that I won't be able to develop new features for this project in the near future. But: I will probably be able to discuss and merge pull-requests, and to publish new versions." You might call that abandoned, I would call it "on hold". I will also invite anyone who is interested in contributing to the project. – Nils Knappmeier Nov 24 '16 at 10:35
1

Found that `spectacle` generates much better-looking documentation from swagger JSON – eternalthinker Mar 24 '18 at 23:21
Note to users checking this thread: SPECTACLE does not work anymore. npm installation results in error. – bbh Aug 18 '22 at 11:22

score 33 · Answer 3 · answered Sep 29 '17 at 07:41

33

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.

answered Sep 29 '17 at 07:41

oseiskar

3,282
2
22
22

Also available as a docker now! https://github.com/yousan/swagger-yaml-to-html – noamtm Dec 13 '20 at 16:16

score 27 · Answer 4 · answered Jun 15 '18 at 03:41

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

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

1

Awesome, thanks! I have used – Erando Sep 28 '18 at 08:05

score 19 · Answer 5 · answered Feb 13 '17 at 22:10

19

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.

answered Feb 13 '17 at 22:10

TLJ

4,525
2
31
46

1

I've found pretty-swag to be a straightforward and ideal tool, with appropriate CLI and API entry points. My one and only complaint (and the one which forced me to deal with the complexity of swagger-ui instead) was its failure to correctly handle object composition/extension. Any use of `allOf` in the document produces `undefined`, even in the simplest scenarios ("merging" a single object, equivalent to not using `allOf` at all). – HonoredMule Jun 01 '17 at 20:17
3

Just rolled out `allOf` feature for you. Check it out. – TLJ Jun 03 '17 at 20:27
2

Does not appear to support Swagger/OpenAPI V3 – SeinopSys Aug 17 '19 at 13:40

score 16 · Answer 6 · edited Jun 09 '18 at 20:59

16

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.

edited Jun 09 '18 at 20:59

maaartinus

44,714
32
161
320

answered Jan 13 '15 at 19:00

djb

4,930
1
34
37

Thanks. My problem was the swagger-ui was not accepting 2.0 spec. However, this looks like the simplest answer, so I will accept this (for now). – Salil Jan 14 '15 at 13:34
The Swagger tools are still evolving for 2.0. However, I've found Swagger UI does work for my 2.0 files that start with "swagger": "2.0", – djb Jan 15 '15 at 15:20
Also, from the Swagger Editor, you can export the JSON spec (not as YAML but as JSON) and the Swagger UI should be able to read that. (Note: the swagger.json must be on the same host/port as the Swagger UI app, or you must enable CORS; see the README.md in the Swagger Editor on GitHub – djb Jan 15 '15 at 15:22

score 9 · Answer 7 · answered Aug 02 '17 at 16:02

9

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

answered Aug 02 '17 at 16:02

user1928596

1,503
16
21

This approach was easiest for me. – Tiber Septim Aug 04 '21 at 17:06

score 7 · Answer 8 · answered Oct 29 '19 at 18:28

7

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

answered Oct 29 '19 at 18:28

Kumar S

431
2
6
16

None of the other suggestions worked for me, but this one did. This was the simplest solution and worked very well. Should be the most upvoted answer. – Stephen Oller Feb 01 '21 at 12:07
Do you mean this https://editor.swagger.io/? – surfmuggle Oct 04 '22 at 13:30

iamdual · Answer 9 · 2022-11-07T19:04:33.937

3

Redocly's CLI interface has a tool to build HTML docs from OpenAPI spec files.

sudo npm i -g @redocly/cli
redocly build-docs my-swagger.yml -o docs.html

edited Nov 07 '22 at 19:04

answered Nov 04 '22 at 19:46

iamdual

1,251
14
11

redoc-cli is deprecated and now it's rebranded as redocly. – Kita Apr 07 '23 at 01:40

score 2 · Answer 10 · answered Sep 24 '14 at 13:08

2

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.

answered Sep 24 '14 at 13:08

Syed Raza Mehdi

4,067
1
31
47

1

Is there an online editor (other than swagger-editor) that can generate this for me? I do not want to annotate my PHP APIs if there is a simpler way. The problem, I have figured out is that swagger-editor generates swagger spec v2.0, and swagger-ui does not handle that as of now. – Salil Sep 25 '14 at 14:22
@Salil all i know is that swagger provides it own on-line editor i.e. http://editor.swagger.wordnik.com/ i am not aware of any other on-line editor, if you find any share it with us, thanks :) – Syed Raza Mehdi Sep 29 '14 at 04:30

score 2 · Answer 11 · answered Nov 23 '21 at 06:29

2

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

answered Nov 23 '21 at 06:29

trax

739
8
21

wow, that sounds nice. Wish they could do that 7 years, 2 months ago :-) – Salil Nov 26 '21 at 10:06

score 1 · Answer 12 · answered Sep 28 '18 at 07:43

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.

score 1 · Answer 13 · answered Aug 31 '23 at 13:22

1

I'm very happy with rapidoc : https://rapidocweb.com/

Why I liked it :

Easy to use
'Try' option
Possible to add code sample.
Integration in other html page
Possible to add css and change layout

answered Aug 31 '23 at 13:22

Tim Zwinkels

340
4
10

Converting Swagger specification JSON to HTML documentation

13 Answers13

Linked