Generate static docs with swagger - swagger

Question

Is there a method for creating static documentation for swagger 2.0?
Perhaps like the 'preview' on editor.swagger.io.
I need to get static html files so I can include them in some static documents.
So far I've not found a way to do this. I see there is swagger-codegens static-docs
but this only works for swagger <= 1.2.

Answer 1

Use swagger-codegen:
swagger-codegen generate -i <path to your swagger file> -l html2 -o <path to output location>
If you decide to customize the HTML template:
Clone the swagger-codegen project from github
Copy modules/swagger-codegen/src/main/resources/htmlDocs2 folder to another place, for example: cp -R modules/swagger-codegen/src/main/resources/htmlDocs2 ~/templates
Modify the .mustache templates in ~/templates to fit your requirements.
Run: swagger-codegen generate -i <path to your swagger file> -l html2 -o <path to output location> -t <templates path> for <templates path> should be ~/templates in the example above.

Answer 2

If you'd just like to generate static docs in a straightforward way, consider Spectacle.
npm install spectacle-docs if you want to put a script in your package.json, or npm install -g spectacle-docs if it should be available everywhere.
Then you can just run spectacle spec.yaml, with options to build to a specific directory, run a server, and/or watch the specfile and update as needed.

Answer 3

You can use the swagger-codegen command as others have mentioned, but the output that you get from using -l html or -l html2 is not interactive like the Swagger UI.
To get an interactive static page like the Swagger UI, follow these steps:
Install
Go to https://github.com/swagger-api/swagger-ui/releases and download the latest release as a .zip file.
Unzip the file and copy everything in the ./dist folder over to the directory that you want the webserver to serve up. For example, Gitlab Pages needs it needs to be in the ./public folder in your repository.
Copy over your swagger.yml file to the ./public folder.
Open up the ./public/index.html file and update the URL to where the swagger file will be on the webserver. For a local server, it might be this: url: "http://localhost:8000/swagger.yml
Test
To test this out, you can run a simple HTTP server using python3.
python3 -m http.server 8000 --directory public
Open up http://localhost:8000/ and check it out!

Answer 4

I usually do it with https://editor.swagger.io/. No installation or anything required.
Copy your yml file into the editor and choose 'Generate Client > html2' and it will generate static html files in a zip file.

Answer 5

The static-docs in 2.0 is implemented for 2.0. see the ./bin/static-docs.sh here:
https://github.com/swagger-api/swagger-codegen/tree/master/bin

Answer 6

You can use:
swagger-ui : just git clone the project and copy your JSON in the base directory
swagger-codegen

Answer 7

OpenAPI 3
For rendering an OpenAPI 3 specification into self-contained HTML file, redoc-cli can be used. You can use ReDoc's Petstore OpenAPI 3 spec as example.
mkdir -p -m 777 build && docker run --rm --user 1000 \
-v $PWD/build:/tmp/build -w /tmp/build \
-v $PWD/openapi.yaml:/tmp/openapi.yaml node:14-slim npx -q \
redoc-cli bundle /tmp/openapi.yaml
This will generate build/redoc-static.html in your current directory.
To avoid waiting for installation, you can also build yourself a Docker image with redoc-cli according to their Dockerfile, or installing redoc-cli to your OS, if you have NodeJS there, with npm install -g redoc-cli.
OpenAPI 2
ReDoc also has compatibility mode for OpenAPI 2/Swagger, so the above also works for Petstore OpenAPI 2 spec.
[ReDoc Compatibility mode]: Converting OpenAPI 2.0 to OpenAPI 3.0
Alternatively, the there's OpenAPI 2-only Spectacle and its official Docker image. It can be used similarly like:
mkdir -p -m 777 build && docker run --rm --user 1000 \
-v $PWD/build:/tmp/build \
-v $PWD/swagger.yaml:/tmp/swagger.yaml sourcey/spectacle \
spectacle -t /tmp/build /tmp/swagger.yaml
It generates static build which is almost self-contained (except loading jQuery from code.jquery.com which was slow for some reason on my end).
├── index.html
├── javascripts
│   ├── spectacle.js
│   └── spectacle.min.js
└── stylesheets
├── foundation.css
├── foundation.min.css
├── spectacle.css
└── spectacle.min.css

Answer 8

I've been using OpenAPI Generator CLI Docker Image https://github.com/OpenAPITools/openapi-generator
it can generate server, clients and docs. for each language there are template files so you can modify the behaviour as needed
I managed to get a python-flask server generated and self hosting generated documentation.
the below will generate an html file that includes code examples for a client
USER=$(shell id -u)
GROUP=$(shell id -g)
MDIR=$(shell pwd)
docker run --rm --user ${USER} -u\:${GROUP} \
-v ${MDIR}:/local openapitools/openapi-generator-cli generate \
--package-name EXAMPLE \
-t /local/.openapi-generator-html-client/ \
-i /local/EXAMPLE.v1.yaml \
-g html2 \
-o /local/openapi_docs

Answer 9

If your specifically looking for for Swagger 2.0, I'd like to point you to my answer in
Converting Swagger specification JSON to HTML documentation
, although I believe that Swagger-Codegen supports Swagger 2.0 by now.

Answer 10

"static" docs can mean several things.
If you're looking for an interactive display (like the editor's preview), you have swagger-ui (https://github.com/swagger-api/swagger-ui).
The code in the codegen that does the more static docs (without the "Try it now" button, for example) is not implemented yet for 2.0 though should be available in the upcoming few weeks.

Answer 11

Clik on preview docs, use chrome addon 'Save Page WE' (right click on page -> 'save page we'), result is single html file (its not clickable so you have to click up everything you want to be seen).

Answer 12

Include dependency for swagger in your pom.
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
And try hitting -> https://editor.swagger.io/