Special Topics¶
Solutions to specific problems are documented here.
Adding Additional Fields To Schema Objects¶
To add additional fields (e.g. "discriminator"
) to Schema objects generated from spec.components.schema
, pass them
to the component
parameter. If your’e using MarshmallowPlugin
, the component
properties will get merged with the autogenerated properties.
properties = {
"id": {"type": "integer", "format": "int64"},
"name": {"type": "string", "example": "doggie"},
}
spec.components.schema("Pet", component={"discriminator": "petType"}, schema=PetSchema)
Note
Be careful about the input that you pass to component
. apispec
will not guarantee that the passed fields are valid against the OpenAPI spec.
Rendering to YAML or JSON¶
YAML¶
spec.to_yaml()
Note
to_yaml
requires PyYAML
to be installed. You can install
apispec with YAML support using:
pip install 'apispec[yaml]'
JSON¶
import json
json.dumps(spec.to_dict())
Documenting Top-level Components¶
The APISpec
object contains helpers to add top-level components.
To add a schema (f.k.a. “definition” in OAS v2), use
spec.components.schema
.
Likewise, parameters and responses can be added using
spec.components.parameter
and
spec.components.response
.
To add other top-level objects, pass them to the APISpec
as keyword arguments.
Here is an example that includes a Server Object.
import yaml
from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
from apispec.utils import validate_spec
OPENAPI_SPEC = """
openapi: 3.0.2
info:
description: Server API document
title: Server API
version: 1.0.0
servers:
- url: http://localhost:{port}/
description: The development API server
variables:
port:
enum:
- '3000'
- '8888'
default: '3000'
"""
settings = yaml.safe_load(OPENAPI_SPEC)
# retrieve title, version, and openapi version
title = settings["info"].pop("title")
spec_version = settings["info"].pop("version")
openapi_version = settings.pop("openapi")
spec = APISpec(
title=title,
version=spec_version,
openapi_version=openapi_version,
plugins=(MarshmallowPlugin(),),
**settings
)
validate_spec(spec)
When adding components, the main advantage of using dedicated methods over
passing them as kwargs is the ability to use plugin helpers. For instance,
MarshmallowPlugin
has helpers to
resolve schemas in parameters and responses.
Documenting Security Schemes¶
Use spec.components.security_scheme
to document Security Scheme Objects.
from pprint import pprint
from apispec import APISpec
spec = APISpec(title="Swagger Petstore", version="1.0.0", openapi_version="3.0.2")
api_key_scheme = {"type": "apiKey", "in": "header", "name": "X-API-Key"}
jwt_scheme = {"type": "http", "scheme": "bearer", "bearerFormat": "JWT"}
spec.components.security_scheme("api_key", api_key_scheme)
spec.components.security_scheme("jwt", jwt_scheme)
pprint(spec.to_dict()["components"]["securitySchemes"], indent=2)
# { 'api_key': {'in': 'header', 'name': 'X-API-Key', 'type': 'apiKey'},
# 'jwt': {'bearerFormat': 'JWT', 'scheme': 'bearer', 'type': 'http'}}