Skip to content

Files

Latest commit

 

History

History
113 lines (83 loc) · 2.99 KB

quickstart.rst

File metadata and controls

113 lines (83 loc) · 2.99 KB

Quickstart

Basic Usage

First, create an APISpec <apispec.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 <apispec.core.Components.schema>.

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

Add paths to your spec using path <apispec.APISpec.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 <apispec.APISpec.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 <apispec.APISpec.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: []
.. 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>`.