Flask中通过Docstring为APISpec添加示例遇阻求助

你的问题核心在于**$ref的YAML语法错误**，同时需要确保APISpec对OpenAPI 3.x的支持，具体修复步骤如下：

• 修正Docstring中$ref的写法：YAML中以#开头的字符串必须加引号，否则会被解析为注释导致引用失效。修改后的Request配置如下：

  requestBody:
      required: true
      content:
        application/json:
          schema: Request
          examples:
            Example1:
              $ref: "#/components/examples/Example1"
  

• 确认APISpec版本：必须使用支持OpenAPI 3.x的APISpec版本（建议v0.39.0及以上），组件示例引用是OpenAPI 3的特性，基于OpenAPI 2的旧版本不支持该语法。

• 验证Schema注册：确保Request Schema已通过spec.components.schema正确注册，示例代码：

  spec.components.schema("Request", {
      "type": "object",
      "properties": {
          "field1": {"type": "string"},
          "field2": {"type": "integer"}
      }
  })
  

• 完整的Spec初始化示例：

  from apispec import APISpec
  from flask_apispec import FlaskApiSpec
  from flask import Flask
  
  app = Flask(__name__)
  spec = APISpec(
      title='你的API',
      version='1.0.0',
      openapi_version='3.0.2',  # 必须指定OpenAPI 3版本
  )
  docs = FlaskApiSpec(app)
  
  # 注册Request Schema
  spec.components.schema("Request", {
      "type": "object",
      "properties": {
          "field1": {"type": "string"},
          "field2": {"type": "integer"}
      }
  })
  
  # 注册Example1组件
  spec.components.example('Example1', {
    "field1": "one",
    "field2": 2
  })
  
  # 注册蓝图接口文档
  docs.register(func, blueprint=blueprint_one)
  

完成以上修改后，Swagger UI即可正确引用你注册的Example1示例。

内容的提问来源于stack exchange，提问作者swygerts