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:
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:
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]
Security Contact Information
To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.
Project Links
Changelog: https://apispec.readthedocs.io/en/latest/changelog.html
Contributing Guidelines: https://apispec.readthedocs.io/en/latest/contributing.html
License
MIT licensed. See the bundled LICENSE file for more details.
Release files for apispec 6.6.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| apispec-6.6.1.tar.gz | 76.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| apispec-6.6.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 106.9 kB
Release files / apispec-6.6.1.tar.gz
| Download URL | apispec-6.6.1.tar.gz |
|---|---|
| Size | 76.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f5caa47cee75fe03b9c50b5594048b4c052eeca2c212e0dac12dbb6175d9a659
|
|
BLAKE2b-256 checksum How to use checksums |
ab5b5d94e1ec6a8e487c026b2a7518dfb7ea90c4c82db48de33c227b7c9141fb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/5.0.0 CPython/3.12.3
|
Release files / apispec-6.6.1-py3-none-any.whl
| Download URL | apispec-6.6.1-py3-none-any.whl |
|---|---|
| Size | 30.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6460315cb38ac6a2ff42d9e2b8dc0435c37d4428d3abeda96ff97b5dc8eb6b94
|
|
BLAKE2b-256 checksum How to use checksums |
ec0f1d0aabf69a9a1bdf8ed1461a2ec7b4036ff4da501f6db2e37634b01860e3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/5.0.0 CPython/3.12.3
|
