跳转到主要内容

一个可插拔的API规范生成器。目前支持OpenAPI规范(以前称为Swagger规范)。

项目描述

PyPI version Build status Documentation marshmallow 3 only OpenAPI Specification 2/3 compatible code style: black

一个可插拔的API规范生成器。目前支持OpenAPI规范(以前称为Swagger规范)。

特性

  • 支持OpenAPI规范(版本2和3)

  • 框架无关

  • 内置对marshmallow的支持

  • 解析文档字符串的实用工具

安装

$ pip install -U apispec

在使用棉花糖插件时,请确保使用兼容的棉花糖版本。

$ 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


# 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)

生成的OpenAPI规范

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: []

文档

文档可在https://apispec.readthedocs.io/ 查找。

生态系统

有关apispec相关库的列表可在GitHub wiki中找到

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

支持apispec

apispec由一群志愿者维护。如果您想支持项目的未来,请考虑向我们的Open Collective捐赠。

Donate to our collective

专业支持

通过Tidelift订阅可以获得专业支持。

Tidelift为软件开发团队提供了一个购买和维护其软件的单一来源,同时与现有工具无缝集成,并从最了解其专家那里获得专业级保障。[获取专业支持]

Get supported apispec with Tidelift

安全联系方式

如需报告安全漏洞,请使用Tidelift安全联系方式。Tidelift将协调修复和披露。

许可证

MIT授权。有关更多详细信息,请参阅捆绑的LICENSE文件。

项目详情


发布历史 发布通知 | RSS源

下载文件

下载您平台对应的文件。如果您不确定选择哪个,请了解更多关于安装包的信息。

源分发

apispec-6.6.1.tar.gz (76.5 kB 查看散列值)

上传时间

构建分发

apispec-6.6.1-py3-none-any.whl (30.4 kB 查看散列值)

上传时间 Python 3

由以下机构支持

AWS AWS 云计算和安全赞助商 Datadog Datadog 监控 Fastly Fastly CDN Google Google 下载分析 Microsoft Microsoft PSF 赞助商 Pingdom Pingdom 监控 Sentry Sentry 错误记录 StatusPage StatusPage 状态页