Snippets

Code usage examples and snippets

Reusable Components

Reusable examples and other components can be adding to the components using:

from flaskdoc import swagger, register_openapi

examples = {
    "foo": swagger.Example(value=10)
}
links = {
    "l1": swagger.Link(operation_id="L!")
}

register_openapi(app, info, examples=examples, links=links)

Reference Objects

Resuable components can be referenced using proper ReferenceObject

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
@swagger.GET(
    tags=["getVersionDetailsv2"],
    summary="Show API versions details",
    responses={
        "200": swagger.ResponseObject(
            description="200 response",
            content=swagger.JsonType(examples={"foo": swagger.ExampleReference("v2-foo")}),
        ),
        "300": swagger.ResponseObject(
            description="300 response",
            content=swagger.JsonType(examples={"foo": swagger.ExampleReference("v2-foo")}),
        ),
    },
)
@api.route("/v2", methods=["GET"])
def details():
    return flask.jsonify(examples["v2-foo"])

Defining Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
examples = {
    "foo": swagger.Example(
        value={
            "versions": [
                {
                    "status": "CURRENT",
                    "updated": "2011-01-21T11:33:21Z",
                    "id": "v2.0",
                    "links": [{"href": "http://127.0.0.1:8774/v2/", "rel": "self"}],
                },
                {
                    "status": "EXPERIMENTAL",
                    "updated": "2013-07-23T11:33:21Z",
                    "id": "v3.0",
                    "links": [{"href": "http://127.0.0.1:8774/v3/", "rel": "self"}],
                },
            ]
        }
    ),
    "v2-foo": swagger.Example(
        value={
            "version": {
                "status": "CURRENT",
                "updated": "2011-01-21T11:33:21Z",
                "media-types": [
                    {
                        "base": "application/xml",
                        "type": "application/vnd.openstack.compute+xml;version=2",
                    },
                    {
                        "base": "application/json",
                        "type": "application/vnd.openstack.compute+json;version=2",
                    },
                ],
                "id": "v2.0",
                "links": [
                    {"href": "http://23.253.228.211:8774/v2/", "rel": "self"},
                    {
                        "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf",
                        "type": "application/pdf",
                        "rel": "describedby",
                    },
                    {
                        "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl",
                        "type": "application/vnd.sun.wadl+xml",
                        "rel": "describedby",
                    },
                ],
            }
        }
    ),
}

Using Enums

1
2
3
4
5
class RepositoryState(enum.Enum):

    open = "open"
    merged = "merged"
    declined = "declined"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
get_pull_requests_by_repository = swagger.GET(
    operation_id="getPullRequestByRepository",
    parameters=[
        swagger.PathParameter(name="username", schema=str,),
        swagger.PathParameter(name="slug", schema=str),
        swagger.QueryParameter(name="state", schema=schemas.RepositoryState),
    ],
    responses={
        "200": swagger.ResponseObject(
            description="an array of pull request objects",
            content=swagger.JsonType(schema=[schemas.PullRequest]),
        )
    },
)