Python Flask 蓝图 - 在一个 .yaml 文件中为多个端点定义 API 文档 其他资源

问题描述

我的一个蓝图中有一些端点，我希望将此蓝图的所有 API 文档添加到单个 .yaml 文件中。但是，根据我当前的 .yaml 文件结构和蓝图代码，flagger 似乎无法识别正确的定义。

蓝图代码：

app_obj = Flask(name)
app_obj.register_blueprint(user_controller,url_prefix="/")
# ...

user_controller = Blueprint("controllers/user_controller",__name__)

@user_controller.route('/signup',endpoint='signup',methods=['POST'])
@swag_from('user.yml',endpoint=f'{user_controller.name}.signup')
def signup():
    response = RestResponse()
    try:
        if request.method == "POST":
            data = request.get_json()
            newly_created_user = UserService.create_user(data.get("username"),data.get("email"),data.get("password"),data.get("name"))
            response.data = newly_created_user
        return jsonify(response.to_dict())
    except BadRequest as err:
        response.data = GenericException(message=err.description).to_dict()
        return jsonify(response.to_dict()),err.code

至于我的user.yaml：

deFinitions:
  User:
    type: object
    properties:
      id:
        type: string
      name:
        type: string
      username:
        type: string
      email:
        type: string
      created_at:
        type: string
      updated_at:
        type: string

paths:
  "/signup":
    post:
      parameters:
        - name: name
          in: body
          type: string
          required: true
        - name: username
          in: body
          type: string
          required: true
        - name: password
          in: body
          type: string
          required: true
        - email: email
          in: body
          type: string
          required: true
      responses:
        200:
          description: Newly created user
          schema:
            $ref: '#/deFinitions/User'

这就是 /apidocs 对我来说的样子：

感谢我能得到的所有帮助。谢谢！

解决方法

不完全是您想要的，而是将规范保存在单个文件中的一种方法是在 Swagger 实例上定义 template_file 参数。 template_file 表示规范文件的完整路径。例如，如果您定义了一个 application factory，我很确定您将能够通过以下示例实现某些目标：

app.py

from flask import Flask
from flasgger import Swagger

def create_app():
    """create_app function."""
    app = Flask(__name__)

    @app.shell_context_processor
    def _shell_context():
        return {"app": app}

    swagger = Swagger(app,template_file='my_spec.yaml')

    with app.app_context():
        app.register_blueprint(my_route)

    return app

注意到 template_file 参数了吗？您必须提供规范文件的完整路径，并且它必须是 yaml 文件。您可以使用以下内容作为示例：

my_spec.yaml

swagger: '2.0'

################################################################################
#                              API Information                                 #
################################################################################
info:
  version: '1.0.0'
  title: My Api Swagger
  description: |
    This tests many paths for my swagger

################################################################################
#                  Host,Base Path,Schemes and Content Types                  #
################################################################################
# The host (name or ip) serving the API
host: localhost:3000

# The base path on which the API is served,relative to the host. Will be prefixed to all paths. Used to control versioning
basePath: /v1/

# The transfer protocol of the API
schemes:
  - http
# Format of bodies a client can send (Content-Type)
consumes:
  - application/json
# Format of the responses to the client (Accepts)
produces:
  - application/json

################################################################################
#                                    Paths                                     #
################################################################################
paths:
  /test:
    get:
      summary: Test 1
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: request
          description: request
          required: true
      responses:
        '200':
          description: OK
  /test2:
    get:
      summary: Test 2
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: request
          description: request
          required: true
      responses:
        '200':
          description: A User object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          description: The user ID.
        username:
          type: string
          description: The user name.

这样，您的所有配置都将依赖于一个文件。您甚至不必在每个端点上都使用 swag_from()。

重要的是通知访问 Flasgger 的默认 uri 是：
/apidocs/#/

因此，在我们上面的示例中，要访问您将使用的 swagger：
http://localhost:3000/apidocs/#/

其他资源

• 来自 Flasgger 本身的单个文件规范示例：
  https://github.com/flasgger/flasgger/blob/master/examples/test_refs.py

• 如何更改flagger上swagger的默认配置：
  https://github.com/flasgger/flasgger#customize-default-configurations

• 用于创建模板的 Swagger 文档：
  https://swagger.io/docs/specification/2-0/basic-structure/