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.