128

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.

Improve this question
1

13 Answers 13

Reset to default
124

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
Improve this answer
Sign up to request clarification or add additional context in comments.

9 Comments

This tool makes really the most beautiful output of all tools mentioned.
Using direct executable name not always works, execution by npx redoc-cli ... is more dependable.
wow. It took me under a minute to have all that doc in one file - on a Mac; is npm now built in? Thanks!
small update: redoc-cli now wants you to use the build option instead of bundle.
Tried this and it told me it was deprecated, and to use npmjs.com/package/@redocly/cli instead.
|
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

Improve this answer

4 Comments

Warning: As of 11/2016 the author of bootprint-swagger apparently has abandoned the project. swagger-codegen is still well supported.
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.
Found that spectacle generates much better-looking documentation from swagger JSON
Note to users checking this thread: SPECTACLE does not work anymore. npm installation results in error.
39

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.

Improve this answer

1 Comment

Also available as a docker now! github.com/yousan/swagger-yaml-to-html
30

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)

Improve this answer

2 Comments

Awesome, thanks! I have used <link rel="stylesheet" href="petstore.swagger.io/swagger-ui.css"> <script src="petstore.swagger.io/swagger-ui-bundle.js"></script>
<link rel="stylesheet" href="cdnjs.cloudflare.com/ajax/libs/swagger-ui/4.11.1/swagger-ui.css"> <script src="cdnjs.cloudflare.com/ajax/libs/swagger-ui/4.11.1/…>
19

Check out pretty-swag

It has

  1. Similar looking as Swagger-Editor's right panel
  2. Search / Filter
  3. Schema Folding
  4. Live Feedback
  5. 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.

Improve this answer

3 Comments

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).
Just rolled out allOf feature for you. Check it out.
Does not appear to support Swagger/OpenAPI V3
17

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.

Improve this answer

3 Comments

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).
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",
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
10

EDIT: 2024-04-22
You can now use docker compose like this with openapi.json next to your compose file and containing the spec:

version: '3'
services:
  swagger-ui:
    image: swaggerapi/swagger-ui
    container_name: swagger-ui
    ports:
      - "8080:8080"
    environment:
      SWAGGER_JSON: /openapi/openapi.json
    volumes:
      - ./openapi.json:/openapi/openapi.json

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

Improve this answer

1 Comment

This approach was easiest for me.
8

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

Improve this answer

2 Comments

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.
Do you mean this editor.swagger.io?
6

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
Improve this answer

1 Comment

redoc-cli is deprecated and now it's rebranded as redocly.
2

Give a look at this link : http://zircote.com/swagger-php/installation.html

  1. Download phar file https://github.com/zircote/swagger-php/blob/master/swagger.phar
  2. Install Composer https://getcomposer.org/download/
  3. Make composer.json
  4. Clone swagger-php/library
  5. Clone swagger-ui/library
  6. Make Resource and Model php classes for the API
  7. Execute the PHP file to generate the json
  8. Give path of json in api-doc.json
  9. Give path of api-doc.json in index.php inside swagger-ui dist folder

If you need another help please feel free to ask.

Improve this answer

2 Comments

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 all i know is that swagger provides it own on-line editor i.e. editor.swagger.wordnik.com i am not aware of any other on-line editor, if you find any share it with us, thanks :)
2

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

Improve this answer

1 Comment

wow, that sounds nice. Wish they could do that 7 years, 2 months ago :-)
1

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.

Improve this answer

Comments

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
Improve this answer

Comments

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.