Special Topics

Adding Additional Fields To Schema Objects

To add additional fields (e.g. "discriminator") to Schema objects generated from spec.components.schema <apispec.core.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)

Rendering to YAML or JSON

spec.to_yaml()

pip install 'apispec[yaml]'

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 <apispec.core.Components.schema>.

Likewise, parameters and responses can be added using spec.components.parameter <apispec.core.Components.parameter> and spec.components.response <apispec.core.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 <apispec.ext.marshmallow.MarshmallowPlugin> has helpers to resolve schemas in parameters and responses.

Documenting Security Schemes

Use spec.components.security_scheme <apispec.core.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'}}