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

Question

I'm going to load initial definitions from marshmallow schemas with Flasgger and APISpec. Also along with that, I want to have multiple version API doc. Here is my code:

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)

I'm also trying to load API doc in .yaml format with this decorator in each route of blueprints:

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

But when I use APISpec template, specs routes don't work anymore! It doesn't filter docs and just loads all of them (v0 and v1) together! Is there any problem with my code or my solution is completely wrong?

Answer 1

Finally, I found a solution (maybe not the best, but it works fine).

It's easy, just remove the template argument from Swagger(...) input, instead of that, add definitions to configs dict. Let's see the final result:

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)