An MkDocs plugin to generate a markdown file containing an API reference built using Swagger UI from a base OAS3 specification.
Project description
mkdocs-swagger-ui
A MkDocs plugin created to help developer embed API Reference documentation into a mkdocs powered website.
The output file can be modified by editing a template file.
Setup
Install the plugin using pip:
pip install mkdocs-swagger-ui
Activate the plugin in mkdocs.yml
:
plugins:
- swagger-ui:
spec_url: 'https://netstorage.ringcentral.com/dpw/api-reference/specs/rc-platform.yml'
outfile: 'docs/api.md'
Options
spec_url
: Sets the URL to the Swagger specification for the RingCentral platform. This should default to the official URL. Override this for development purposes only.outfile
: The file to output. This file is typically somewhere in your docs folder.template
: The name of the template file that generates the contents of the Swagger UI generated page. This file should be located in atmpl
directory.
More information about plugins in the MkDocs documentation.
How the plugin works
This plugin works by generating a markdown file prior to the rest of a mkdocs project being built. In other words, as soon as mkdocs is started, this plugin downloads a spec file, parses it, generates a markdown file, and saves that file into the documentation tree. Then to make the generated page appear in your documentation, you add the file to your pages
tree. For example:
plugins:
- swagger-ui:
outfile: api/quick-reference.md
pages:
- 'Home': index.md
- 'Quick Reference': api/quick-reference.md
See Also
More information about templates here.
More information about blocks here.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mkdocs_swagger_ui-0.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a667e962787c7f142962c47d4a2442e76289187eb8c75ea5fcfebe097a032877 |
|
MD5 | 89e22c6993b59aac8658a2ae17a5abab |
|
BLAKE2b-256 | 858be77f4f3edd0e5b1f43ea8c793437e375dcb36b6a7c1f2af2120231b4b70c |