Serve a documentation site
The toolkit has a command to serve a spec json document and optionally a UI for a given spec. It embeds redoc, so you can use that documentation site without an internet connection. Or it can load your local spec into the swagger docs viewer at http://petstore.swagger.io
Usage
To serve a documentation site:
Usage:
swagger [OPTIONS] serve [serve-OPTIONS]
serve a spec and swagger or redoc documentation ui
Application Options:
-q, --quiet silence logs
--log-output=LOG-FILE redirect logs to file
Help Options:
-h, --help Show this help message
[serve command options]
--base-path= the base path to serve the spec and UI at
-F, --flavor=[redoc|swagger] the flavor of docs, can be swagger or redoc (default: redoc)
--doc-url= override the url which takes a url query param to render the doc ui
--no-open when present won't open the the browser to show the url
--no-ui when present, only the swagger spec will be served
-p, --port= the port to serve this site [$PORT]
--host= the interface to serve this site, defaults to 0.0.0.0 [$HOST]
This will start a server with cors enabled so that sites on other domains can load your specification document.
Flavors
At this moment the UI can be served into 2 flavors.
Redoc
The swagger source code has a middleware for embedding Redoc. So for the redoc flavor we make use of that and use it with the spec you have on disk.
Swagger UI
For the swagger flavor we use the UI hosted at http://petstore.swagger.io. The server has CORS enabled and appends the url for the spec JSON to the petstore url as a query string.
Your own UI
You can use your own UI by pointing it to the spec served by this command.
When no ui is being served, the terminal will print the url to the spec document.
You can also use the --doc-url
to provide another url as base.
The url to your documentation site for example, which would need to recognize the query param url to load the swagger spec from, through the browser.
More
There are some more options for this command which you can view with:
swagger serve --help