Skip to main content

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

Project description

PyPI package Build status Documentation marshmallow 3|4 compatible OpenAPI Specification 2/3 compatible

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

Installation

$ pip install -U apispec

When using the marshmallow plugin, ensure a compatible marshmallow version is used:

$ pip install -U apispec[marshmallow]

Example Application

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):
    category = fields.List(fields.Nested(CategorySchema))
    name = fields.Str()


# Optional security scheme support
api_key_scheme = {"type": "apiKey", "in": "header", "name": "X-API-Key"}
spec.components.security_scheme("ApiKeyAuth", api_key_scheme)


# Optional Flask support
app = Flask(__name__)


@app.route("/random")
def random_pet():
    """A cute furry animal endpoint.
    ---
    get:
      description: Get a random pet
      security:
        - ApiKeyAuth: []
      responses:
        200:
          content:
            application/json:
              schema: PetSchema
    """
    pet = get_random_pet()
    return PetSchema().dump(pet)


# 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))
# {
#   "paths": {
#     "/random": {
#       "get": {
#         "description": "Get a random pet",
#         "security": [
#           {
#             "ApiKeyAuth": []
#           }
#         ],
#         "responses": {
#           "200": {
#             "content": {
#               "application/json": {
#                 "schema": {
#                   "$ref": "#/components/schemas/Pet"
#                 }
#               }
#             }
#           }
#         }
#       }
#     }
#   },
#   "tags": [],
#   "info": {
#     "title": "Swagger Petstore",
#     "version": "1.0.0"
#   },
#   "openapi": "3.0.2",
#   "components": {
#     "parameters": {},
#     "responses": {},
#     "schemas": {
#       "Category": {
#         "type": "object",
#         "properties": {
#           "name": {
#             "type": "string"
#           },
#           "id": {
#             "type": "integer",
#             "format": "int32"
#           }
#         },
#         "required": [
#           "name"
#         ]
#       },
#       "Pet": {
#         "type": "object",
#         "properties": {
#           "name": {
#             "type": "string"
#           },
#           "category": {
#             "type": "array",
#             "items": {
#               "$ref": "#/components/schemas/Category"
#             }
#           }
#         }
#       }
#       "securitySchemes": {
#          "ApiKeyAuth": {
#            "type": "apiKey",
#            "in": "header",
#            "name": "X-API-Key"
#         }
#       }
#     }
#   }
# }

print(spec.to_yaml())
# components:
#   parameters: {}
#   responses: {}
#   schemas:
#     Category:
#       properties:
#         id: {format: int32, type: integer}
#         name: {type: string}
#       required: [name]
#       type: object
#     Pet:
#       properties:
#         category:
#           items: {$ref: '#/components/schemas/Category'}
#           type: array
#         name: {type: string}
#       type: object
#   securitySchemes:
#     ApiKeyAuth:
#       in: header
#       name: X-API-KEY
#       type: apiKey
# info: {title: Swagger Petstore, version: 1.0.0}
# openapi: 3.0.2
# paths:
#   /random:
#     get:
#       description: Get a random pet
#       responses:
#         200:
#           content:
#             application/json:
#               schema: {$ref: '#/components/schemas/Pet'}
#       security:
#       - ApiKeyAuth: []
# tags: []

Documentation

Documentation is available at https://apispec.readthedocs.io/ .

Ecosystem

A list of apispec-related libraries can be found at the GitHub wiki here:

https://github.com/marshmallow-code/apispec/wiki/Ecosystem

Support apispec

apispec is maintained by a group of volunteers. If you’d like to support the future of the project, please consider contributing to our Open Collective:

Donate to our collective

Professional Support

Professionally-supported apispec is available through the Tidelift Subscription.

Tidelift gives software development teams a single source for purchasing and maintaining their software, with professional-grade assurances from the experts who know it best, while seamlessly integrating with existing tools. [Get professional support]

Get supported apispec with Tidelift

Security Contact Information

To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.

License

MIT licensed. See the bundled LICENSE file for more details.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

apispec-6.8.2.tar.gz (77.1 kB view details)

Uploaded Source

Built Distribution

apispec-6.8.2-py3-none-any.whl (30.5 kB view details)

Uploaded Python 3

File details

Details for the file apispec-6.8.2.tar.gz.

File metadata

  • Download URL: apispec-6.8.2.tar.gz
  • Upload date:
  • Size: 77.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for apispec-6.8.2.tar.gz
Algorithm Hash digest
SHA256 ce5b69b9fcf0250cb56ba0c1a52a75ff22c2f7c586654e57884399018c519f26
MD5 7c7cbbbcf848e6a626bcf64219799fae
BLAKE2b-256 c0212b86a14a01c800308226c018fa489991cc40ffc227954d4f59d8a4090477

See more details on using hashes here.

Provenance

The following attestation bundles were made for apispec-6.8.2.tar.gz:

Publisher: build-release.yml on marshmallow-code/apispec

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file apispec-6.8.2-py3-none-any.whl.

File metadata

  • Download URL: apispec-6.8.2-py3-none-any.whl
  • Upload date:
  • Size: 30.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for apispec-6.8.2-py3-none-any.whl
Algorithm Hash digest
SHA256 43c52ab6aa7d4056c1dfc6c81310c659b29f4db5858b3b4351819b77d3a1afff
MD5 55a13ece462a2e68f007f775ac0c7060
BLAKE2b-256 f786a2e7e0f6e9a82023108f52014eab389b184a06da486139fc5436d50b08d0

See more details on using hashes here.

Provenance

The following attestation bundles were made for apispec-6.8.2-py3-none-any.whl:

Publisher: build-release.yml on marshmallow-code/apispec

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page