README.md

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:

• py2swagger
• swagger2rst
• sphinx-confluence
• confluence-publisher

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 /api

Additional 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 Smith

paths

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: kevin

types

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: false

Examples priorities

If a field has several examples, the following priority rules apply

1. Example from operation.
2. 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.
3. Example from primitive types.