Quickstart

Basic Usage

First, create an APISpec object, passing basic information about your API.

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.

spec.components.schema(
    "Gist",
    {
        "properties": {
            "id": {"type": "integer", "format": "int64"},
            "name": {"type": "string"},
        }
    },
)

Add paths to your spec using path.

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:

spec.path(...).path(...).tag(...)

spec.components.schema(...).parameter(...)

To output your OpenAPI spec, invoke the to_dict method.

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 to export your spec to YAML.

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: []

See also

For a full reference of the APISpec class, see the Core API Reference.

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: Using Plugins.