0

我试图通过引用同一个 YAML 文件来记录多个端点，但它不起作用。这不支持吗？还是我做错了什么？

应用程序.py

from flask import Flask, jsonify
from flasgger import Swagger

app = Flask(__name__)
Swagger(app)

@app.route('/colors1/<palette>/')
def colors1(palette):
    """
    file: ../colors.yaml
    """
    all_colors = {
        'cmyk': ['cyan', 'magenta', 'yellow', 'black'],
        'rgb': ['red', 'green', 'blue']
    }
    if palette == 'all':
        result = all_colors
    else:
        result = {palette: all_colors.get(palette)}

    return jsonify(result)

@app.route('/colors2/<palette>/')
def colors2(palette):
    """
    file: ../colors.yaml
    """
    all_colors = {
        'cmyk': ['cyan', 'magenta', 'yellow', 'black'],
        'rgb': ['red', 'green', 'blue']
    }
    if palette == 'all':
        result = all_colors
    else:
        result = {palette: all_colors.get(palette)}

    return jsonify(result)

颜色.yaml

Multiple endpoint specs
---
paths:
  /colors1/:
    get:
      parameters:
        - name: palette
          in: path
          type: string
          enum: ['all', 'rgb', 'cmyk']
          required: true
          default: all
      responses:
        200:
          description: A list of colors (may be filtered by palette)
          schema:
            $ref: '#/components/schema/Palette'
          examples:
            rgb: ['red', 'green', 'blue']
  /colors2/:
    get:
      parameters:
        - name: palette
          in: path
          type: string
          enum: ['all', 'rgb', 'cmyk']
          required: true
          default: all
      responses:
        200:
          description: A list of colors (may be filtered by palette)
          schema:
            $ref: '#/components/schema/Palette'
          examples:
            rgb: ['red', 'green', 'blue']
components:
  schemas:
    Palette:
      type: object
      properties:
        palette_name:
          type: array
          items:
            $ref: '#/components/schema/Color'
    Color:
      type: string

预期结果

具有完整规范（示例、响应、参数等）的两个端点，就像 README 中的屏幕截图中的规范一样。

实际结果

规格不完整，缺少很多细节：

图片

4

1 回答 1

0

为什么它不起作用？

Flasgger 似乎不支持在单个外部 YAML 文件中包含多个规范。因此，您需要将每个端点规范放在一个单独的文件中。

为什么 Swagger-UI 中缺少细节？

colors.yaml您的文件中存在一些问题：

解决方案 1. 使用 OpenAPI 2.0

这是colors.yamlFlasgger可以理解的外观

Colors endpoint spec
---

parameters:
  - name: palette
    in: path
    type: string
    enum:
      - all
      - rgb
      - cmyk
    required: true
    default: all

responses:
  '200':
    description: A list of colors (may be filtered by palette)
    schema:
      $ref: '#/definitions/Palette'
    examples:
      rgb:
        - red
        - green
        - blue

definitions:
  Palette:
    type: object
    properties:
      palette_name:
        type: array
        items:
          $ref: '#/definitions/Color'
    example:
      rgb:
        - red
        - green
        - blue
  Color:
    type: string
    example: red

解决方案 2. 使用 OpenAPI 3（Flasgger 不完全支持）

根据 Flasgger repo，OpenAPI 3 支持是实验性的

有对 OpenAPI 3.0 的实验性支持，在使用 SwaggerUI 3 时应该可以工作。

因此，在 OpenAPI 3 模式下使用带有外部规范文件的 Flasgger 是可能的，但并非所有情况都受支持。例如，关于使用components外部 YAML 文件的引用存在一个未解决的问题（参见问题#308）。

如果你仍然坚持下去，这就是你应该做的。

步骤 1. 启用 OpenAPI 3

app.config在您的app.py文件中更新：

app = Flask(__name__)
app.config['SWAGGER'] = {
    'openapi': '3.0.0'
}
swagger = Swagger(app)

步骤 2. 更新规范以使用 OpenAPI 3

colors.yaml使用以下内容更新您的文件。

重要提示：请注意，$ref由于上述问题，我们不得不内联模型模式定义而不是使用规范。

Colors endpoint spec
---

parameters:
  - name: palette
    in: path
    schema:
      type: string
      enum: ['all', 'rgb', 'cmyk']
      default: all
    required: true

responses:
  200:
    description: A list of colors (may be filtered by palette)
    content:
      application/json:
        schema:
          type: object
          properties:
            palette_name:
              type: array
              items:
                type: string
                example: red
          example:
            rgb:
              - red
              - green
              - blue
        example:
          rgb: ['red', 'green', 'blue']
于 2021-12-20T13:52:33.033 回答