Swagger to .rst Converter
Why?
This tools are written as part of our Documentation Toolkit which we use in our job daily. The main idea of toolkit is to make a process of creating and updating documentation able to be automated
Other parts of our toolkit is:
Install
Install from PyPI with
$ pip install swagger2rst
Usage examples
Command - swg2rst
Required arguments: - path - path to a swagger file (“json” or “yaml”) - --format (-f) - output file format. Currenty only “rst” is supported (required)
Options: - --output (-o) - output filename (default: stdout) - --template (-t) - custom template file path (default: templates/basic.) - --examples(-e) - custom examples definitions file path (“json” or “yaml”) - --inline (-i) - put schema definitions in paths, otherwise in a separate Data Structures section
Example:
> swg2rst samples/swagger.json -f rst -o /home/user/rst_docs/swagger.rst
> swg2rst samples/swagger.json -f rst -o /home/user/rst_docs/swagger.rst -e /home/user/examples.yaml
> cat docs/swagger.json | swg2rst -f rst -t templates/custom.rst | grep /apiAdditional enhancements
To convert GFM descriptions into restructuredText install pandoc and use custom Jinja filter md2rst
> sudo apt-get install pandoc
> pip install pypandoc{{ doc.info['description']|md2rst }}Custom Examples
Custom examples are described in json or yaml. See samples directory.
Elements
array_items_count
Number of elements in all arrays. Set from 1 to 5. Default: 2.
definitions
Bind fields to examples by definition schemas. Key is a definition reference path, value is an object (key is a field name and value is an example):
json
{
"definitions": {
"#/definitions/Media": {
"likes.count": 10,
"likes.data.user_name": "liked_user",
"user.user_name": "my_login"
},
"#/definitions/MiniProfile": {
"user_name": "some_login",
"full_name": "John Smith"
}
}
}yaml
definitions:
'#/definitions/Media':
likes.count: 10
likes.data.user_name: liked_user
user.user_name: my_login
'#/definitions/MiniProfile':
user_name: some_login
full_name: John Smithpaths
Bind operation fields to examples by path. Should define path, method, section (parameters or responses) and field name
json
{
"paths": {
"/users/{user-id}/relationship": {
"post": {
"parameters": {
"action": "approve"
},
"responses": {
"200.data": {
"profile_picture": "picture",
"full_name": "Kevin Jones",
"id": 10,
"user_name": "kevin"
}
}
}
}
}
}yaml
paths:
/users/{user-id}/relationship:
post:
parameters:
action: approve
responses:
200.data.profile_picture: picture
200.data.full_name: Kevin Jones
200.data.id: 10
200.data.user_name: kevintypes
Define examples for primitive types.
Supported types: - string - date - date-time - number - integer - boolean
json
{
"types": {
"string": "value",
"date": "2000-12-01",
"date-time": "2000-12-01T12:00:00.000Z",
"number": 1.2,
"integer": 5,
"boolean": false
}
}yaml
types:
string: value
date: '2000-12-01'
date-time: '2000-12-01T12:00:00.000Z'
number: 1.2
integer: 5
boolean: falseExamples priorities
If a field has several examples, the following priority rules apply
Example from operation.
Example from definitions. If a schema has nested schemas, the priority is given to an example from a most descriptive. E.g.: Media has nested schema MiniProfile. For user_name in likes in Media an example will be taken from #/definitions/Media/likes.data.user_name rather than from #/definitions/MiniProfile/user_name.
Example from primitive types.
Release files for swagger2rst 0.0.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| swagger2rst-0.0.4-py2.py3-none-any.whl | Python 3, Python 2 | none | any | Details for swagger2rst-0.0.4-py2.py3-none-any.whl |
Release files / swagger2rst-0.0.4-py2.py3-none-any.whl
| Download URL | swagger2rst-0.0.4-py2.py3-none-any.whl |
|---|---|
| Size | 33.4 kB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
7bc4eb1d3a80b04e2db0afdc8669a5eb491003d88e5a34e784f7a90df734078a
|
|
BLAKE2b-256 checksum How to use checksums |
7b5767a49b214f4f40bfaec8d825889cd38878ad16aa473e0767964bb442bbd4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
Security for swagger2rst 0.0.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
