Swagger 3.0示例请求中List等数据类型映射失败求助

问题分析 #

你当前配置里的exampleSetFlag并非OpenAPI 3.0官方规范参数，可能干扰Swagger UI对schema与示例的解析逻辑；另外如果#/components/schemas/MyPartnerCardInfoRequest的定义和外层example结构不匹配，也会导致类型映射失效。

修复步骤 #

1. 移除非规范参数exampleSetFlag

OpenAPI 3.0没有exampleSetFlag这个官方字段，直接删除schema和content里的该参数，避免UI解析出错。

2. 确保组件Schema正确定义数据类型

检查MyPartnerCardInfoRequest的schema定义，必须明确标注字段类型，比如cards为数组类型，内部字段为字符串类型，示例如下：

components:
  schemas:
    MyPartnerCardInfoRequest:
      type: object
      properties:
        cards:
          type: array
          items:
            type: object
            properties:
              cardId:
                type: string
              templateId:
                type: string
              cardVariantId:
                type: string
              componentId:
                type: string
          description: 卡片列表

3. 统一示例配置方式

有两种推荐的示例配置方式，选其一即可：

方式一：在Schema内部定义示例

把示例放在schema对应字段中，让Swagger UI自动关联类型与示例：

components:
  schemas:
    MyPartnerCardInfoRequest:
      type: object
      properties:
        cards:
          type: array
          items:
            type: object
            properties:
              cardId:
                type: string
                example: "HERO_LOYALTY_WELCOME_CARD"
              templateId:
                type: string
                example: "partner_welcome_card"
              cardVariantId:
                type: string
                example: "partner_welcome_card"
              componentId:
                type: string
                example: "basesheet"
          example:
            - cardId: "HERO_LOYALTY_WELCOME_CARD"
              templateId: "partner_welcome_card"
              cardVariantId: "partner_welcome_card"
              componentId: "basesheet"
            - cardId: "HERO_LOYALTY_BANNER_CARD"
              templateId: "partner_welcome_card"
              cardVariantId: "partner_welcome_card"
              componentId: "basesheet"

方式二：在requestBody的content里使用examples（而非单个example）

如果需要多个示例，用examples字段明确关联schema，确保类型映射正确：

requestBody:
  description: "MyPartner Cards Request"
  content:
    application/json:
      schema:
        $ref: "#/components/schemas/MyPartnerCardInfoRequest"
      examples:
        default:
          summary: 默认卡片请求示例
          value:
            cards:
              - cardId: "HERO_LOYALTY_WELCOME_CARD"
                templateId: "partner_welcome_card"
                cardVariantId: "partner_welcome_card"
                componentId: "basesheet"
              - cardId: "HERO_LOYALTY_BANNER_CARD"
                templateId: "partner_welcome_card"
                cardVariantId: "partner_welcome_card"
                componentId: "basesheet"
  required: true

4. 验证Swagger UI版本

确保使用的Swagger UI是3.x及以上版本，旧版本对OpenAPI 3.0的支持不完善，可能导致类型映射异常。

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