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
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
Quickstart
==========
Basic Usage
-----------
First, create an `APISpec <apispec.APISpec>` object, passing basic information about your API.
.. code-block:: python
from apispec import APISpec
spec = APISpec(
title="Gisty",
version="1.0.0",
openapi_version="3.0.2",
info=dict(description="A minimal gist API"),
)
Add schemas to your spec using `spec.components.schema <apispec.core.Components.schema>`.
.. code-block:: python
spec.components.schema(
"Gist",
{
"properties": {
"id": {"type": "integer", "format": "int64"},
"name": {"type": "string"},
}
},
)
Add paths to your spec using `path <apispec.APISpec.path>`.
.. code-block:: python
spec.path(
path="/gist/{gist_id}",
operations=dict(
get=dict(
responses={"200": {"content": {"application/json": {"schema": "Gist"}}}}
)
),
)
The API is chainable, allowing you to combine multiple method calls in
one statement:
.. code-block:: python
spec.path(...).path(...).tag(...)
spec.components.schema(...).parameter(...)
To output your OpenAPI spec, invoke the `to_dict <apispec.APISpec.to_dict>` method.
.. code-block:: python
from pprint import pprint
pprint(spec.to_dict())
# {'components': {'parameters': {},
# 'responses': {},
# 'schemas': {'Gist': {'properties': {'id': {'format': 'int64',
# 'type': 'integer'},
# 'name': {'type': 'string'}}}}},
# 'info': {'description': 'A minimal gist API',
# 'title': 'Gisty',
# 'version': '1.0.0'},
# 'openapi': '3.0.2',
# 'paths': {'/gist/{gist_id}':
# {'get': {'responses': {'200': {'content': {'application/json': {'schema': {'$ref': '#/definitions/Gist'}}}}}}}},
# 'tags': []}
Use `to_yaml <apispec.APISpec.to_yaml>` to export your spec to YAML.
.. code-block:: python
print(spec.to_yaml())
# components:
# parameters: {}
# responses: {}
# schemas:
# Gist:
# properties:
# id: {format: int64, type: integer}
# name: {type: string}
# info: {description: A minimal gist API, title: Gisty, version: 1.0.0}
# openapi: 3.0.2
# paths:
# /gist/{gist_id}:
# get:
# responses:
# '200':
# content:
# application/json:
# schema: {$ref: '#/definitions/Gist'}
# tags: []
.. seealso::
For a full reference of the `APISpec <apispec.APISpec>` class, see the :doc:`Core API Reference <api_core>`.
Next Steps
----------
We've learned how to programmatically construct an OpenAPI spec, but defining our entities was verbose.
In the next section, we'll learn how to let plugins do the dirty work: :doc:`Using Plugins <using_plugins>`.
|
