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.
swagger-codegen generate -i <path to your swagger file> -l html2 -o <path to output location>
modules/swagger-codegen/src/main/resources/htmlDocs2 folder to another place, for example: cp -R modules/swagger-codegen/src/main/resources/htmlDocs2 ~/templates.mustache templates in ~/templates to fit your requirements.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:
url: "http://localhost:8000/swagger.ymlTo 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!
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.
Update: there's actually a pre-built Docker image in the project's GitHub Docker registry, e.g. ghcr.io/redocly/redoc/cli:v2.0.0-rc.76.
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.
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
You can use:
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 Converting Swagger specification JSON to HTML documentation , although I believe that Swagger-Codegen supports Swagger 2.0 by now.
Generating documentation is not actually necessary; all you need is an OpenAPI/Swagger file.
You can simply use swagger-ui-dist which consumes OpenAPI/Swagger file, this module exposes Swagger-UI's entire dist folder as a dependency-free npm module.
Example:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="description" content="SwaggerIU" />
<title>SwaggerUI</title>
<link rel="stylesheet" href="https://esm.sh/swagger-ui@4.19.0/dist/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script type="importmap">
{
"imports": {
"swagger-ui-dist": "https://esm.sh/swagger-ui-dist@4.19.0/",
}
}
</script>
<script type="module" src="./main.js"></script>
</body>
</html>
Add your url: <...> to openapi file.
// main.js
// @ts-check
import swagger from "swagger-ui-dist"
const ui = swagger.SwaggerUIBundle({
url: 'https://petstore3.swagger.io/api/v3/openapi.json',
dom_id: '#swagger-ui',
})
To enable autocomplete for swagger-ui-dist, you can initialize npm by running npm init -y and then install using npm i -D @types/swagger-ui-dist.
"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.
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/
