Generate static docs with swagger

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.

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:

1. Clone the swagger-codegen project from github
2. Copy modules/swagger-codegen/src/main/resources/htmlDocs2 folder to another place, for example: cp -R modules/swagger-codegen/src/main/resources/htmlDocs2 ~/templates
3. Modify the .mustache templates in ~/templates to fit your requirements.
4. 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.

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.

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!

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

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

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.

You can use:

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

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

If your specifically looking for for Swagger 2.0, I'd like to point you to my answer in https://stackoverflow.com/questions/25800493/converting-swagger-,specification-json-to-html-documentation/31096794#answer-31096794 , although I believe that Swagger-Codegen supports Swagger 2.0 by now.

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

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

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/