Sphinx extension for documenting Swagger 2.0 APIs
pip install sphinxcontrib-swaggerdoc
Include extension in conf.py
extensions = ['sphinxcontrib.swaggerdoc']
Add directive pointing to a remote Swagger api-docs
.. swaggerv2doc:: URL/swagger.json
or to a local file
.. swaggerv2doc:: PATH/swagger.json
For example
.. swaggerv2doc:: http://petstore.swagger.io/v2/swagger.json
If the Swagger description contains multiple tags, you can select a subset for the documentation generation. For example, the following directive only generates the documentation for the methods contained in tags pet and store.
.. swaggerv2doc:: http://petstore.swagger.io/v2/swagger.json
pet
store
You can also use use YAML defined swagger specs. But you will need to install this distribution with the yaml
requirements extra (i.e. sphinx-swaggerdoc[yaml]
); or manually install PyYAML. Note, YAML is used when the file exention is .yaml
or .yml
.
.. swaggerv2doc:: PATH/swagger.yaml
The old directive for Swagger 1.0 is still usable. For example,
.. swaggerdoc:: http://petstore.swagger.wordnik.com/api/api-docs/pet
.. swaggerdoc:: http://petstore.swagger.wordnik.com/api/api-docs/user
.. swaggerdoc:: http://petstore.swagger.wordnik.com/api/api-docs/store