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

Defining Examples

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

Using Enums

1class RepositoryState(enum.Enum):
2
3    open = "open"
4    merged = "merged"
5    declined = "declined"

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