apispec

Release v3.1.0 (Changelog)

A pluggable API specification generator. Currently supports the OpenAPI Specification (f.k.a. the Swagger specification).

Features

  • Supports the OpenAPI Specification (versions 2 and 3)

  • Framework-agnostic

  • Built-in support for marshmallow

  • Utilities for parsing docstrings

Example Application

import uuid

from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
from apispec_webframeworks.flask import FlaskPlugin
from flask import Flask
from marshmallow import Schema, fields


# Create an APISpec
spec = APISpec(
    title="Swagger Petstore",
    version="1.0.0",
    openapi_version="3.0.2",
    plugins=[FlaskPlugin(), MarshmallowPlugin()],
)

# Optional marshmallow support
class CategorySchema(Schema):
    id = fields.Int()
    name = fields.Str(required=True)


class PetSchema(Schema):
    categories = fields.List(fields.Nested(CategorySchema))
    name = fields.Str()


# Optional Flask support
app = Flask(__name__)


@app.route("/random")
def random_pet():
    """A cute furry animal endpoint.
    ---
    get:
      description: Get a random pet
      responses:
        200:
          description: Return a pet
          content:
            application/json:
              schema: PetSchema
    """
    # Hardcoded example data
    pet_data = {
        "name": "sample_pet_" + str(uuid.uuid1()),
        "categories": [{"id": 1, "name": "sample_category"}],
    }
    return PetSchema().dump(pet_data)


# Register the path and the entities within it
with app.test_request_context():
    spec.path(view=random_pet)

Generated OpenAPI Spec

import json

print(json.dumps(spec.to_dict(), indent=2))
# {
#   "info": {
#     "title": "Swagger Petstore",
#     "version": "1.0.0"
#   },
#   "openapi": "3.0.2",
#   "components": {
#     "schemas": {
#       "Category": {
#         "type": "object",
#         "properties": {
#           "id": {
#             "type": "integer",
#             "format": "int32"
#           },
#           "name": {
#             "type": "string"
#           }
#         },
#         "required": [
#           "name"
#         ]
#       },
#       "Pet": {
#         "type": "object",
#         "properties": {
#           "categories": {
#             "type": "array",
#             "items": {
#               "$ref": "#/components/schemas/Category"
#             }
#           },
#           "name": {
#             "type": "string"
#           }
#         }
#       }
#     }
#   },
#   "paths": {
#     "/random": {
#       "get": {
#         "description": "Get a random pet",
#         "responses": {
#           "200": {
#             "description": "Return a pet",
#             "content": {
#               "application/json": {
#                 "schema": {
#                   "$ref": "#/components/schemas/Pet"
#                 }
#               }
#             }
#           }
#         }
#       }
#     }
#   },
# }

print(spec.to_yaml())
# info:
#   title: Swagger Petstore
#   version: 1.0.0
# openapi: 3.0.2
# components:
#   schemas:
#     Category:
#       properties:
#         id:
#           format: int32
#           type: integer
#         name:
#           type: string
#       required:
#       - name
#       type: object
#     Pet:
#       properties:
#         categories:
#           items:
#             $ref: '#/components/schemas/Category'
#           type: array
#         name:
#           type: string
#       type: object
# paths:
#   /random:
#     get:
#       description: Get a random pet
#       responses:
#         '200':
#           content:
#             application/json:
#               schema:
#                 $ref: '#/components/schemas/Pet'
#           description: Return a pet