https://github.com/bharel/mkdocs-render-swagger-plugin
A plugin for MKDocs for rendering swagger & openapi schemas using SwaggerUI.
https://github.com/bharel/mkdocs-render-swagger-plugin
Last synced: 5 months ago
JSON representation
A plugin for MKDocs for rendering swagger & openapi schemas using SwaggerUI.
- Host: GitHub
- URL: https://github.com/bharel/mkdocs-render-swagger-plugin
- Owner: bharel
- License: mit
- Created: 2020-12-15T12:41:17.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2023-10-07T05:23:19.000Z (over 1 year ago)
- Last Synced: 2024-03-15T02:51:59.915Z (about 1 year ago)
- Language: Python
- Size: 71.3 KB
- Stars: 62
- Watchers: 3
- Forks: 11
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- jimsghstars - bharel/mkdocs-render-swagger-plugin - A plugin for MKDocs for rendering swagger & openapi schemas using SwaggerUI. (Python)
README
# mkdocs-render-swagger-plugin
This is the [Mkdocs](https://www.mkdocs.org) plugin for rendering swagger & openapi schemas using [Swagger UI](https://swagger.io/tools/swagger-ui/). It is written in Python.[](https://github.com/bharel/mkdocs-render-swagger-plugin/actions)
[](https://pypi.org/project/mkdocs-render-swagger-plugin/)
[](https://pypi.org/project/mkdocs-render-swagger-plugin/)
[](https://codecov.io/gh/bharel/mkdocs-render-swagger-plugin)## Usage
Install the plugin using `pip install mkdocs-render-swagger-plugin`.Add the following lines to your mkdocs.yml:
plugins:
- render_swagger## Example
Here's an [example](https://docs.scarf.sh/api-v2/) (courtesy of Scarf) of how the plugin renders swagger.
### Referencing a local json
Place an OpenAPI json file in the same folder as the `.md` file.
Enter `!!swagger FILENAME!!` at the appropriate location inside the markdown file.
If you wish to reference any files on the filesytem (security risk), make sure
you enable `allow_arbitrary_locations` in the config (mkdocs.yml) like so:plugins:
- render_swagger:
allow_arbitrary_locations : true### Referencing an external json
You may reference an external OpenAPI json using the following syntax: `!!swagger-http URL!!`.
## Explicit declaration of the Swagger JS library
You can explicitly specify the swagger-ui css and js dependencies if you wish to not use the unpkg CDN.
To specify this use `javascript` and `css` in your mkdocs.yaml:
```yaml
plugins:
- render_swagger:
javascript: assets/js/swagger-ui-bundle.js
css: assets/css/swagger-ui.css
```## Contributing & Developing Locally
After downloading and extracting the `.tar.gz`, install this package locally using `pip` and the `--editable` flag:
```bash
pip install --editable ".[dev]"
```You'll then have the `render-swagger` package available to use in Mkdocs and `pip` will point the dependency to this folder. You are then able to run the docs using `mkdocs serve`. Make sure you restart the process between code changes as the plugin is loaded on startup.
## MkDocs plugins and Swagger api
The Render Swagger MkDocs plugin uses a set of extensions and plugin APIs that MkDocs and Swagger UI supports.
You can find more info about MkDocs plugins and Swagger UI on the official website of [MkDocs](https://www.mkdocs.org/user-guide/plugins/) and [SwaggerUI](https://github.com/swagger-api/swagger-ui/blob/master/docs/customization/plugin-api.md).The input OpenAPI files processed by the plugin should conform to the [OpenAPI specification](https://swagger.io/specification/). It is generated by a few projects such as [pydantic](https://pydantic-docs.helpmanual.io/), [FastAPI](https://fastapi.tiangolo.com/) and others.
Disclaimer: This plugin is unofficial, and is not sponsored, owned or endorsed by mkdocs, swagger, or any other 3rd party.
Credits to @aviramha for starting this project.