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

Navigation

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for lafrech from gravatar.com lafrech Avatar for sloria from gravatar.com sloria

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License
  • Author: Steven Loria
  • Maintainer: Steven Loria
  • Tags apispec , swagger , openapi , specification , oas , documentation , spec , rest , api
  • Requires: Python >=3.10
  • Provides-Extra: dev , docs , marshmallow , tests , yaml
Classifiers
Report project as malware

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

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for lafrech from gravatar.com lafrech Avatar for sloria from gravatar.com sloria

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License
  • Author: Steven Loria
  • Maintainer: Steven Loria
  • Tags apispec , swagger , openapi , specification , oas , documentation , spec , rest , api
  • Requires: Python >=3.10
  • Provides-Extra: dev , docs , marshmallow , tests , yaml
Classifiers

Release history Release notifications | RSS feed

This version

6.10.0

6.9.0

6.8.4

6.8.3

6.8.2

6.8.1

6.8.0

6.7.1

6.7.0

6.6.1

6.6.0

6.5.0

6.4.0

6.3.1

6.3.0

6.2.0

6.1.0

6.0.2

6.0.1

6.0.0

6.0.0b1 pre-release

5.2.2

5.2.1

5.2.0

5.1.1

5.1.0

5.0.0

5.0.0b1 pre-release

4.7.1

4.7.0

4.6.0

4.5.0

4.4.2

4.4.1

4.4.0

4.3.0

4.2.0

4.1.0

4.0.0

4.0.0b1.post0 pre-release

3.3.2

3.3.1

3.3.0

3.2.0

3.1.1

3.1.0

3.0.0

2.0.2

2.0.1

2.0.0

1.3.3

1.3.2

1.3.1

1.3.0

1.2.1

1.2.0

1.1.2

1.1.1

1.1.0

1.0.0

1.0.0rc1 pre-release

1.0.0b6 pre-release

1.0.0b5 pre-release

1.0.0b4 pre-release

1.0.0b3 pre-release

1.0.0b2 pre-release

1.0.0b1 pre-release

0.39.0

0.38.0

0.37.1

0.37.0

0.36.0

0.35.0

0.34.0

0.33.0

0.32.0

0.31.0

0.30.0

0.29.0

0.28.0

0.27.1

0.27.0

0.26.0

0.25.4

0.25.3

0.25.2

0.25.1

0.25.0

0.24.0

0.23.1

0.23.0

0.22.3

0.22.2

0.22.1

0.22.0

0.21.0

0.20.1

0.20.0

0.19.0

0.18.0

0.17.4

0.17.3

0.17.2

0.17.1

0.17.0

0.16.0

0.15.0

0.14.0

0.13.0

0.12.0

0.11.1

0.11.0

0.10.1

0.10.0

0.9.1

0.9.0

0.8.0

0.7.0

0.6.0

0.5.0

0.4.2

0.4.1

0.4.0

0.3.0

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.10.0.tar.gz (80.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

apispec-6.10.0-py3-none-any.whl (31.3 kB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for apispec-6.10.0.tar.gz
Algorithm Hash digest
SHA256 0a888555cd4aa5fb7176041be15684154fd8961055e1672e703abf737e8761bf
MD5 847fa44044377f3e52bf15abc471fe8c
BLAKE2b-256 4af11f5a9332df3ecd90cc5ab69bc58a4174b8ba2ac1720c4c26b01d20751bf5

See more details on using hashes here.

Provenance

The following attestation bundles were made for apispec-6.10.0.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.10.0-py3-none-any.whl.

File metadata

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

File hashes

Hashes for apispec-6.10.0-py3-none-any.whl
Algorithm Hash digest
SHA256 8ff23e0de9a0ceb62ff70047241126315bd17b8d0565a567934c0156f4ddbb43
MD5 93aba4a935f596fd74ebb7e0455fcda9
BLAKE2b-256 2088e149b20246c4689e7d27163e4e3bb8946ef31617cfb3b9c427813483fe5b

See more details on using hashes here.

Provenance

The following attestation bundles were made for apispec-6.10.0-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 Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page