如何在Flasgger中注册Swagger端点

Question

目前使用Swagger/Flasgger/烧瓶记录应用程序中的app /路由。

# app.py
from flask import Flask
from flasgger import Swagger
from myapp.blueprints.main import main

app = Flask(__name__)    
app.register_blueprint(main)
swag = Swagger(app)

# myapp.blueprints.main.views.py
main = Blueprint('main', __name__)    

@main.route('/user/<path:user_id>', methods=['GET', 'PUT', 'DELETE'])
@main.route('/user', methods=['GET', 'POST'])
def user(user_id=None):
    pass

要获得用于同一函数的两条路由的文档，我需要为每个Flasgger文档做两件事

1. 添加指向包含规范的文件的@swag_from声明。
2. 给@main.route和@swag_from同样的endpoint kwarg。

当我执行步骤1时，我开始在Swagger输出中看到规范信息：

# myapp.blueprints.main.views.py
@main.route('/user/<path:user_id>', methods=['GET', 'PUT', 'DELETE'])
@main.route('/user', methods=['GET', 'POST'])
@swag_from('user_without_id.yml')
def user(user_id=None):
    pass

// > curl localhost:8000/apispec_1.json
{
"definitions": {
    "User": {
      "properties": {
        "age": {
          "default": "180", 
          "description": "The user age (should be integer)", 
          "type": "integer"
        }, 
        "tags": {
          "default": [
            "wizard", 
            "hogwarts", 
            "dead"
          ], 
          "description": "optional list of tags", 
          "items": {
            "type": "string"
          }, 
          "type": "array"
        }, 
        "username": {
          "default": "Sirius Black", 
          "description": "The user name.", 
          "type": "string"
        }
      }, 
      "required": [
        "username", 
        "age"
      ]
    }
  }, 
  "info": {
    "description": "The test-swagger-api spec", 
    "termsOfService": "/tos", 
    "title": "test-swagger-api", 
    "version": "1.0"
  }, 
  "paths": {
    "/user": {
      "get": {
        "description": "The default payload is invalid, try it, then change the age to a valid integer and try again<br/>", 
        "parameters": [
          {
            "in": "body", 
            "name": "body", 
            "required": true, 
            "schema": {
              "$ref": "#/definitions/User"
            }
          }
        ], 
        "responses": {
          "200": {
            "description": "A single user item", 
            "schema": {
              "$ref": "#/definitions/User"
            }
          }
        }, 
        "summary": "Test validation using JsonSchema"
      }, 
      "post": {
        "description": "The default payload is invalid, try it, then change the age to a valid integer and try again<br/>", 
        "parameters": [
          {
            "in": "body", 
            "name": "body", 
            "required": true, 
            "schema": {
              "$ref": "#/definitions/User"
            }
          }
        ], 
        "responses": {
          "200": {
            "description": "A single user item", 
            "schema": {
              "$ref": "#/definitions/User"
            }
          }
        }, 
        "summary": "Test validation using JsonSchema"
      }
    }, 
    "/user/{user_id}": {
      "get": {
        "description": "The default payload is invalid, try it, then change the age to a valid integer and try again<br/>", 
        "parameters": [
          {
            "in": "body", 
            "name": "body", 
            "required": true, 
            "schema": {
              "$ref": "#/definitions/User"
            }
          }
        ], 
        "responses": {
          "200": {
            "description": "A single user item", 
            "schema": {
              "$ref": "#/definitions/User"
            }
          }
        }, 
        "summary": "Test validation using JsonSchema"
      }
    }
  }, 
  "swagger": "2.0"
}

但是，一旦我添加了endpoint和methods kwargs，我的输出就失去了规范：

# myapp.blueprints.main.views.py
@main.route('/user/<path:user_id>', methods=['GET', 'PUT', 'DELETE'])
@main.route('/user', endpoint='my-new-endpoint', methods=['GET', 'POST'])
@swag_from('user_without_id.yml', endpoint='my-new-endpoint', methods=['GET', 'POST'])
def user(user_id=None):
    pass

// > curl localhost:8000/apispec_1.json
{
  "definitions": {}, 
  "info": {
    "description": "The test-swagger-api spec", 
    "termsOfService": "/tos", 
    "title": "test-swagger-api", 
    "version": "1.0"
  }, 
  "paths": {}, 
  "swagger": "2.0"
}

不确定文档的去向。Flasgger的蓝图示例并没有展示如何使用一个函数上的多个路由来实现这个功能。

Answer 1

https://stackoverflow.com/a/55109061/3316036

@swag_from需要在其endpoint字段中包含蓝图名称，遗憾的是，flasgger文档中并不清楚这一点。

# myapp.blueprints.main.views.py
@main.route('/user/<path:user_id>', methods=['GET', 'PUT', 'DELETE'])
@main.route('/user', endpoint='my-new-endpoint', methods=['GET', 'POST'])
@swag_from('user_without_id.yml', endpoint='main.my-new-endpoint', methods=['GET', 'POST'])
def user(user_id=None):
    pass