如何在 flasgger 中同时拥有棉花糖定义和多版本规范？

Question

我将使用 Flasgger 和 APISpec 从棉花糖模式加载初始定义。除此之外，我还想拥有多个版本 API 文档。这是我的代码：

from app.api.v1.controllers.assessment_controller import AssessmentCoachingRequestSchema, AssessmentCoachingResponseSchema
from app.api.v1.responses import AssessmentResultResponseSchema, ModuleScoreResponseSchema, RecommendedModulesListResponseSchema, UserModuleScoresListResponseSchema
from app.api.v1.requests import AssessmentCreateRequestSchema, AssessmentShowRequestSchema
from app.api.v1.routes import assesment
from flasgger import Swagger
from flask.app import Flask
from flasgger import APISpec, Schema, Swagger, fields
from apispec.ext.marshmallow import MarshmallowPlugin
from apispec_webframeworks.flask import FlaskPlugin


def configure_swagger(app: Flask):
    # Create an APISpec
    spec = APISpec(
        title='API',
        version='1.0.0',
        openapi_version='2.0',
        plugins=[
            FlaskPlugin(),
            MarshmallowPlugin(),
        ],
    )

    template = spec.to_flasgger(
        app,
        definitions=[AssessmentCreateRequestSchema, AssessmentResultResponseSchema,
                     AssessmentShowRequestSchema, AssessmentCoachingRequestSchema,
                     AssessmentCoachingResponseSchema, UserModuleScoresListResponseSchema,
                     RecommendedModulesListResponseSchema]
    )
    configs = {
        "headers": [
        ],
        "specs": [
            {
                "endpoint": 'v0_spec',
                "route": '/v0',
                "version": "0.0.0",
                "title": "API v0",
                "description": 'Version 0 of the API',
                "rule_filter": lambda rule: rule.endpoint.startswith('api_v0'),
                "model_filter": lambda tag: True,  # all in
            },
            {
                "endpoint": 'v1_spec',
                "route": '/v1',
                "version": "1.0.0",
                "title": "API v1",
                "description": 'Version 1 of the API',
                "rule_filter": lambda rule: rule.endpoint.startswith('api_v1'),
                "model_filter": lambda tag: True,  # all in
            },
            {
                "endpoint": 'test_v1_spec',
                "route": '/tv1',
                "version": "1.0.0",
                "title": "API test v1",
                "description": 'Test version 1 of the API',
                "rule_filter": lambda rule: rule.endpoint.startswith('api_test_v1'),
                "model_filter": lambda tag: True,  # all in
            },
            {
                "endpoint": 'experiment_v1_spec',
                "route": '/exp',
                "version": "1.0.0",
                "title": "API experiment",
                "description": 'Experiment API',
                "rule_filter": lambda rule: rule.endpoint.startswith('api_exp'),
                "model_filter": lambda tag: True,  # all in
            }
        ],
        "static_url_path": "/flasgger_static",
        # "static_folder": "static",  # must be set by user
        "swagger_ui": True,
        "specs_route": "/apidocs/",
        "title": "API",
        "schemes": [
            "http",
            "https"
        ],
        "securityDefinitions": {
            "basicAuth": {
                "type": "http",
                "scheme": "basic"
            }
        },
        "security":{"basicAuth": []}
    }

    swag = Swagger(app, config=configs, template=template)

我还尝试在每个蓝图路径中使用此装饰器以 .yaml 格式加载 API 文档：

@api_v1_blueprint.route('/text-analysis', methods=['GET'])
@swag_from('/app/api/_docs/v1/text_analysis.yaml', methods=["GET"])
@auth.login_required
@validate_request(marshmallow_schema=TextAnalysisRequestSchema)
def text_analysis(request: TextAnalysisRequest):
    return show_response(data=analyze_text(request), response_version=RESPONSE_VERSION)

但是当我使用 APISpec 模板时，specs 路由不再起作用了！它不会过滤文档，只是将所有文档（v0 和 v1）一起加载！是我的代码有问题还是我的解决方案完全错误？

Answer 1

最后，我找到了解决方案（可能不是最好的，但效果很好）。

很简单，只需从 Swagger(...) 输入中删除 template 参数，而不是将 definitions 添加到 configs dict。让我们看看最终结果：

from app.api.v1.controllers.assessment_controller import AssessmentCoachingRequestSchema, AssessmentCoachingResponseSchema
from app.api.v1.responses import AssessmentResultResponseSchema, ModuleScoreResponseSchema, RecommendedModulesListResponseSchema, UserModuleScoresListResponseSchema
from app.api.v1.requests import AssessmentCreateRequestSchema, AssessmentShowRequestSchema
from app.api.v1.routes import assesment
from flasgger import Swagger
from flask.app import Flask
from flasgger import APISpec, Schema, Swagger, fields
from apispec.ext.marshmallow import MarshmallowPlugin
from apispec_webframeworks.flask import FlaskPlugin


def configure_swagger(app: Flask):
    # Create an APISpec
    spec = APISpec(
        title='API',
        version='1.0.0',
        openapi_version='2.0',
        plugins=[
            FlaskPlugin(),
            MarshmallowPlugin(),
        ],
    )

    template = spec.to_flasgger(
        app,
        definitions=[AssessmentCreateRequestSchema, AssessmentResultResponseSchema,
                     AssessmentShowRequestSchema, AssessmentCoachingRequestSchema,
                     AssessmentCoachingResponseSchema, UserModuleScoresListResponseSchema,
                     RecommendedModulesListResponseSchema]
    )
    configs = {
        "headers": [
        ],
        "definitions":template['definitions'],
        "specs": [
            {
                "endpoint": 'v0_spec',
                "route": '/v0',
                "version": "0.0.0",
                "title": "API v0",
                "description": 'Version 0 of the API',
                "rule_filter": lambda rule: rule.endpoint.startswith('api_v0'),
                "model_filter": lambda tag: True,  # all in
            },
            {
                "endpoint": 'v1_spec',
                "route": '/v1',
                "version": "1.0.0",
                "title": "API v1",
                "description": 'Version 1 of the API',
                "rule_filter": lambda rule: rule.endpoint.startswith('api_v1'),
                "model_filter": lambda tag: True,  # all in
            },
            {
                "endpoint": 'test_v1_spec',
                "route": '/tv1',
                "version": "1.0.0",
                "title": "API test v1",
                "description": 'Test version 1 of the API',
                "rule_filter": lambda rule: rule.endpoint.startswith('api_test_v1'),
                "model_filter": lambda tag: True,  # all in
            },
            {
                "endpoint": 'experiment_v1_spec',
                "route": '/exp',
                "version": "1.0.0",
                "title": "API experiment",
                "description": 'Experiment API',
                "rule_filter": lambda rule: rule.endpoint.startswith('api_exp'),
                "model_filter": lambda tag: True,  # all in
            }
        ],
        "static_url_path": "/flasgger_static",
        # "static_folder": "static",  # must be set by user
        "swagger_ui": True,
        "specs_route": "/apidocs/",
        "title": "API",
        "schemes": [
            "http",
            "https"
        ],
        "securityDefinitions": {
            "basicAuth": {
                "type": "http",
                "scheme": "basic"
            }
        },
        "security":{"basicAuth": []}
    }

    swag = Swagger(app, config=configs)

如何在 flasgger 中同时拥有棉花糖定义和多版本规范？

How to have marshmallow definitions and multi-version specs together in flasgger?

python

flask

swagger-ui

flasgger