python 4小时前 · 2026-08-31 18:16:24 · 0 阅读

apispec 6.10.0

可插拔的 API 规范生成器。目前支持 OpenAPI Specification（原名 Swagger specification）。

pip install apispec 复制 PIP 安装说明

可插拔的 API 规范生成器。目前支持 OpenAPI Specification（原名 Swagger specification）。

功能

支持 OpenAPI Specification（版本 2 和 3）
与框架无关
内置支持 marshmallow
提供用于解析文档字符串的工具

安装

$ pip install -U apispec

使用 marshmallow 插件时，请确保使用兼容的 marshmallow 版本：

$ pip install -U apispec[marshmallow]

示例应用

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

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

# 可选的 marshmallow 支持
class CategorySchema(Schema):
    id = fields.Int()
    name = fields.Str(required=True)

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

# 可选的安全方案支持
api_key_scheme = {"type": "apiKey", "in": "header", "name": "X-API-Key"}
spec.components.security_scheme("ApiKeyAuth", api_key_scheme)

# 可选的 Flask 支持
app = Flask(__name__)

@app.route("/random")
def random_pet():
    """一个可爱的毛茸茸动物接口。
    ---
    get:
      description: 获取一只随机宠物
      security:
        - ApiKeyAuth: []
      responses:
        200:
          content:
            application/json:
              schema: PetSchema
    """
    pet = get_random_pet()
    return PetSchema().dump(pet)

# 注册路径及其中的实体
with app.test_request_context():
    spec.path(view=random_pet)

生成的 OpenAPI 规范

import json

print(json.dumps(spec.to_dict(), indent=2))
# {
#   "paths": {
#     "/random": {
#       "get": {
#         "description": "获取随机宠物",
#         "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: 获取随机宠物
#       responses:
#         200:
#           content:
#             application/json:
#               schema: {$ref: '#/components/schemas/Pet'}
#       security:
#       - ApiKeyAuth: []
# tags: []