用于在 swagger 中对方法进行分组的flask-api-spec 标签

Question

I try to group my app-services in swagger. In my project, I use FlaskApiSpec to generate Swagger documentation for my Python-Flask application.

There is a part of code, how I generate swagger docs for my app, using Flask Blueprint pattern:

application/ init .py

from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_apispec.extension import FlaskApiSpec
from apispec.ext.marshmallow import MarshmallowPlugin
from apispec import APISpec

db = SQLAlchemy()
docs = FlaskApiSpec()

def create_app():
   app = Flask(__name__)

   app.config.update({
        'APISPEC_SPEC': APISpec(
            title = 'D&D Master Screen',
            version = 'v0.1',
            openapi_version = '2.0',
            plugins = [MarshmallowPlugin()],
        ),
        'APISPEC_SWAGGER_URL': '/api/swagger/',
        'APISPEC_SWAGGER_UI_URL': '/api/swagger-ui/'
    })
    # Import Blueprints
    from .characters.views import characters_bp
    from .main.views import main_bp

    # Registrate Blueprints
    app.register_blueprint(characters_bp, url_prefix='/api/characters')
    app.register_blueprint(main_bp, url_prefix='/')

    # Initialize Plugins
    db.init_app(app)
    docs.init_app(app)

    return app

application/characters/views.py

from flask import Blueprint
# from application.characters import characters_bp
from flask import jsonify
from flask_apispec import use_kwargs, marshal_with
from application import docs
from application.models import  db, db_add_objects, db_delete_objects, Character
from application.schemas import CharacterSchema, ErrorSchema, CharacterIdSchema

characters_bp = Blueprint('characters_bp', __name__)


@characters_bp.route("/", methods=['GET'])
@marshal_with(CharacterSchema(many = True), code=200)
def characters():
    characters = Character.get_all()
    if characters is None:
        return {"message": "Characters not found"}, 404
    return characters


@characters_bp.route("/<character_id>", methods=['GET'])
@marshal_with(CharacterSchema, code=200)
@marshal_with(ErrorSchema, code=404)
def character(character_id):
    character = Character.get(character_id)
    if character is None:
        return {"message": str("Character with id=" + character_id + " not found")}, 404
    return character
    

@characters_bp.route("/", methods=['POST'])
@use_kwargs(CharacterSchema)
@marshal_with(CharacterIdSchema, code=200)
def create_character(**kwargs):
    new_character = Character(**kwargs)
    db_add_objects(new_character)
    return {"id": new_character.id}
    

@characters_bp.route("/<character_id>", methods=['DELETE'])
@marshal_with(ErrorSchema, code=200)
@marshal_with(ErrorSchema, code=404)
def delete_character(character_id):
    character = Character.get(character_id)
    if character is None:
        return {"message": str("Character with id=" + character_id + " not found")}, 404
    db_delete_objects(character)
    return jsonify({"message": "success"})



# Swagger docs for Characters Module services
blueprint_name = characters_bp.name
docs.register(character, blueprint = blueprint_name)
docs.register(characters, blueprint = blueprint_name)
docs.register(create_character, blueprint = blueprint_name)
docs.register(delete_character, blueprint = blueprint_name)

And result is enter image description here

I want to group my /api/characters methods in one group in swagger, and name it correctly. I try to find a lot on the Internet, and learn something about tags is Swagger. But i don't understand, how to use this functionality in FlaskApiSpec

I suppose that tags can be added somewhere here:

docs.register(character, blueprint = blueprint_name)"

but don't understand how...

Answer 1

我也尝试了很长时间......对我来说有效：只是装饰你的功能

 @docs(tags=['characters'])

Answer 2

Yes, you can assign multiple methods under the same tag by using :

@docs(tags=['characters'])

Use same tag name for all the methods you want to show under the tag name. You can also add a description for every method separately in the tags.

Try this:

@doc(description='Describing GET method', tags=['charavters'])
def get():
    <code here>


@doc(description='Describing POST method', tags=['charavters'])
def post():
    <code here>