示例 Java 中的 Swagger 列表未映射

Question

我正在使用 Swagger 3.0。我无法在 swagger-ui 中映射示例请求中的对象列表。附上屏幕截图以供参考。其他数据类型（例如字符串和映射）也会发生同样的情况。

请求结构 -

"requestBody": {
  "description": "MyPartner Cards Request",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MyPartnerCardInfoRequest",
        "exampleSetFlag": false
      },
      "example": {
        "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"
          }
        ]
      },
      "exampleSetFlag": true
    }
  },
  "required": true
}

期望正确映射数据类型。

Answer 1

这是您准确描述的有效样本。它似乎在 swagger-ui 上工作得很好。不过，您的有效负载中有一个附加属性，它会引发

exampleSetFlag

错误。这不是 OpenAPI 架构中的有效关键字。

不过，你的示例似乎加载得很好

{
  "openapi" : "3.0.3",
  "info" : {
    "title" : "test",
    "version" : "1.0.0"
  },
  "servers" : [ ],
  "paths" : {
    "/endpoint" : {
      "post" : {
        "summary" : "stack",
        "parameters" : [ ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/MyPartnerCardInfoRequest",
                "exampleSetFlag": false
              },
              "example" : {
                "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"
                } ]
              },
              "exampleSetFlag": true
            }
          },
          "required" : true
        },
        "responses" : {
          "201" : {
            "description" : "Created",
            "headers" : {
              "location" : {
                "schema" : {
                  "type" : "string"
                }
              }
            },
            "content" : {
              "application/json" : {
                "schema" : { }
              }
            }
          }
        }
      }
    }
  },
  "components" : {
    "schemas" : {
      "MyPartnerCardInfoRequest" : {
        "type" : "object",
        "properties" : {
          "cards" : {
            "type" : "array",
            "items" : { }
          }
        }
      }
    }
  }
}

OpenAPI 3.x.x 的首选关键字是

examples

（复数）关键字，它接受模式集合。这允许相同有效负载的多个示例。

{
  "openapi": "3.0.3",
  "info": {
    "title": "test",
    "version": "1.0.0"
  },
  "servers": [],
  "paths": {
    "/endpoint": {
      "post": {
        "summary": "stack",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MyPartnerCardInfoRequest"
              },
              "examples": {
                "example_1": {
                  "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
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "location": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "MyPartnerCardInfoRequest": {
        "type": "object",
        "properties": {
          "cards": {
            "type": "array",
            "items": {}
          }
        }
      }
    }
  }
}