pyramid_apispec

pyramid_apispec 允许您使用 OpenAPI规范文件 和 apispec，结合 Swagger UI 项目，为您 Pyramid 应用程序及其 marshmallow 模式创建在线OpenAPI探索器。

安装

pip install pyramid_apispec

基本用法

运行示例文件夹和最小应用程序示例

pip install -e '.[demo]'
python demo/app.py

然后您可以在 http://0.0.0.0:6543/api-explorer 访问您的API探索器页面。

或访问 此处生成的文档 以查看示例站点的示例。（请注意，实际的REST API在GitHub pages中无法工作）

注意： 示例站点使用OpenAPI/Swagger v2.0。同样支持OpenAPI 3.0，它使用不同的YAML模式，请注意在线示例。

示例

此示例基于 apispec，适用于Pyramid和 pyramid_apispec（已根据 apispec v5.1.0 更新）。

本例使用OpenAPI 3.0.2

提示路由及其视图

将OpenAPI YAML添加到视图文档字符串中。可选地使用Marshmallow模式来定义输入和输出。

import uuid

from marshmallow import Schema, fields
from pyramid.view import view_config

# Optional marshmallow support
class CategorySchema(Schema):
    id = fields.Int()
    name = fields.Str(required=True)

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

@view_config(route_name="random_pet", renderer="json")
def random_pet(request):
    """A cute furry animal endpoint.
    ---
    get:
      description: Get a random pet
      security:
        - ApiKeyAuth: []
      responses:
        200:
          description: Return a pet
          content:
            application/json:
              schema: PetSchema
    """
    # Hardcoded example data
    pet_data = {
        "name": "sample_pet_" + str(uuid.uuid1()),
        "categories": [{"id": 1, "name": "sample_category"}],
    }
    return PetSchema().dump(pet_data)

有关如何文档化API的更多详细信息，请参阅OpenAPI规范。

将规范作为JSON响应呈现

from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
from pyramid.view import view_config
from pyramid_apispec.helpers import add_pyramid_paths

@view_config(route_name="openapi_spec", renderer="json")
def api_spec(request):
    """View to generate the OpenAPI JSON output."""
    spec = APISpec(
        title="Some API",
        version="1.0.0",
        openapi_version="3.0.2",
        plugins=[MarshmallowPlugin()],
    )

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

    # Optionally register Marshmallow schema for more flexibility
    spec.components.schema("Pet", schema=PetSchema)

    # inspect the `random_pet` route and generate operations from docstring
    add_pyramid_paths(spec, 'random_pet', request=request)

    return spec.to_dict()

添加API探索视图

为了补充规范文件生成，此包还可以通过Swagger UI项目提供应用程序API的API探索器

config.include("pyramid_apispec.views")
config.add_route("openapi_spec", "/openapi.json")
config.pyramid_apispec_add_explorer(spec_route_name="openapi_spec")

默认情况下，您需要传递在您的应用程序中提供OpenAPI规范的路由名称。如有需要，您可以指定Pyramid permission或自定义可调用项（script_generator参数）以覆盖Swagger UI的默认JavaScript配置。

探索器的默认URL为/api-explorer。此设置通过explorer_route_path参数控制 - 路由注册为pyramid_apispec.api_explorer_path。

运行测试

pip install -e '.[dev]'
tox