# 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`:
```yaml
plugins:
- swagger-ui:
spec_url: 'https://netstorage.ringcentral.com/dpw/api-reference/specs/rc-platform.yml'
outfile: 'docs/api.md'
```
Add the CSS file to your mkdocs.yml:
```yaml
extra_css:
- https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.43.0/swagger-ui.css
```
### 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 a `tmpl` directory.
More information about plugins in the [MkDocs documentation][mkdocs-plugins].
## How the plugin works
This plugin works by loading a different template and markdown file that renders a Swagger UI page in a file's place. The key to making this work is to ensure that the `outfile` plugin config value matches the filename of some file in your documentation tree, as shown below. When mkdocs encounters this file and if the file matches the `outfile` then the plugin will render a Swagger UI in place of whatever file may already be in place. In other words, the contents of the file are completed ignored, and replaced by the output of this plugin.
```yaml
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][mkdocs-template].
More information about blocks [here][mkdocs-block].
[mkdocs-plugins]: https://www.mkdocs.org/user-guide/plugins/
[mkdocs-template]: https://www.mkdocs.org/user-guide/custom-themes/#template-variables
[mkdocs-block]: https://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks
Raw data
{
"_id": null,
"home_page": "https://github.com/byrnereese/mkdocs-swagger-ui",
"name": "mkdocs-swagger-ui",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.0",
"maintainer_email": null,
"keywords": "mkdocs swagger api documentation",
"author": "Byrne Reese",
"author_email": "byrne@majordojo.com",
"download_url": "https://files.pythonhosted.org/packages/13/e6/270a93f77c4e12ce343e830c7ec9862e1820b6bb3d76c473f95bbc315ba6/mkdocs-swagger-ui-0.2.tar.gz",
"platform": null,
"description": "# mkdocs-swagger-ui\n\nA MkDocs plugin created to help developer embed API Reference documentation into a mkdocs powered website. \n\nThe output file can be modified by editing a template file.\n\n## Setup\n\nInstall the plugin using pip:\n\n`pip install mkdocs-swagger-ui`\n\nActivate the plugin in `mkdocs.yml`:\n\n```yaml\nplugins:\n - swagger-ui:\n spec_url: 'https://netstorage.ringcentral.com/dpw/api-reference/specs/rc-platform.yml'\n outfile: 'docs/api.md'\n```\n\nAdd the CSS file to your mkdocs.yml:\n\n```yaml\nextra_css:\n- https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.43.0/swagger-ui.css\n```\n\n### Options\n\n- `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. \n- `outfile`: The file to output. This file is typically somewhere in your docs folder. \n- `template`: The name of the template file that generates the contents of the Swagger UI generated page. This file should be located in a `tmpl` directory.\n\nMore information about plugins in the [MkDocs documentation][mkdocs-plugins].\n\n## How the plugin works\n\nThis plugin works by loading a different template and markdown file that renders a Swagger UI page in a file's place. The key to making this work is to ensure that the `outfile` plugin config value matches the filename of some file in your documentation tree, as shown below. When mkdocs encounters this file and if the file matches the `outfile` then the plugin will render a Swagger UI in place of whatever file may already be in place. In other words, the contents of the file are completed ignored, and replaced by the output of this plugin. \n\n```yaml\nplugins:\n - swagger-ui:\n outfile: api/quick-reference.md\npages:\n - 'Home': index.md\n - 'Quick Reference': api/quick-reference.md\n```\n\n## See Also\n\nMore information about templates [here][mkdocs-template].\n\nMore information about blocks [here][mkdocs-block].\n\n[mkdocs-plugins]: https://www.mkdocs.org/user-guide/plugins/\n[mkdocs-template]: https://www.mkdocs.org/user-guide/custom-themes/#template-variables\n[mkdocs-block]: https://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An MkDocs plugin to generate a markdown file containing an API reference built using Swagger UI from a base OAS3 specification.",
"version": "0.2",
"project_urls": {
"Homepage": "https://github.com/byrnereese/mkdocs-swagger-ui"
},
"split_keywords": [
"mkdocs",
"swagger",
"api",
"documentation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d956d3b32d6db67d3d5eb6d5668fd901a654c486cadc6e9a4bd815f6c22c0ebf",
"md5": "fe6fb70f3a7bb329e0e70ef0232781fd",
"sha256": "e612a67921b8480377a264498dcebbd71c2ae486f7d18a4a1bdee61b087876c3"
},
"downloads": -1,
"filename": "mkdocs_swagger_ui-0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fe6fb70f3a7bb329e0e70ef0232781fd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.0",
"size": 4751,
"upload_time": "2024-04-05T22:03:00",
"upload_time_iso_8601": "2024-04-05T22:03:00.484816Z",
"url": "https://files.pythonhosted.org/packages/d9/56/d3b32d6db67d3d5eb6d5668fd901a654c486cadc6e9a4bd815f6c22c0ebf/mkdocs_swagger_ui-0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "13e6270a93f77c4e12ce343e830c7ec9862e1820b6bb3d76c473f95bbc315ba6",
"md5": "2abe395a57a6ade8987d56aca132e816",
"sha256": "4afe14844db158598f5d0ca25941be09fed6ddc121ffd1db53ec0fcf7508375b"
},
"downloads": -1,
"filename": "mkdocs-swagger-ui-0.2.tar.gz",
"has_sig": false,
"md5_digest": "2abe395a57a6ade8987d56aca132e816",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.0",
"size": 4246,
"upload_time": "2024-04-05T22:03:01",
"upload_time_iso_8601": "2024-04-05T22:03:01.690573Z",
"url": "https://files.pythonhosted.org/packages/13/e6/270a93f77c4e12ce343e830c7ec9862e1820b6bb3d76c473f95bbc315ba6/mkdocs-swagger-ui-0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-05 22:03:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "byrnereese",
"github_project": "mkdocs-swagger-ui",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mkdocs-swagger-ui"
}
JSON
