我在为 OpenAPI 3 中的响应指定 XML 示例时遇到困难

Question

我有一个 OpenAPI 3 的 JSON 文件，其中包含以下内容：

            "trait_hasProjectResponse_200": {
                "description": "",
                "content": {
                    "application/xml": {
                        "example": {
                            "value" : "<project><foo>1</foo><bar>2</bar></project>"
                        }
                    }
                }
            },

这导致在当前 swagger 上显示以下内容-ui:

如何在 OpenAPI 3 规范中为参数或响应指定 XML 的示例？我查看了文档，它似乎主要针对 JSON。我需要做什么来生成 OpenAPI 3 JSON 文件的输出。

我也尝试过使用 externalValue 并且遇到了类似的困难。

Answer 1

从 example 中删除 value 键（value 仅用于多个 examples）。

"example": "<project><foo>1</foo><bar>2</bar></project>"

或者，您可以为响应定义一个 schema，Swagger UI 将根据 schema 生成示例。在您的示例中，架构是一个包含 foo 数组的 project 对象。您可以指定 [1, 2] 作为 foo 数组的示例值：

  "components": {
    "responses": {
      "trait_hasProjectResponse_200": {
        "description": "",
        "content": {
          "application/xml": {
            "schema": {
              "$ref": "#/components/schemas/project"
            }
          }
        }
      }
    },
    "schemas": {
      "project": {
        "type": "object",
        "properties": {
          "foo": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "xml": {
              "wrapped": false
            },
            "example": [1, 2]
          }
        }
      }
    }
  }

这会给你：

我在为 OpenAPI 3 中的响应指定 XML 示例时遇到困难

I am having difficulty specifying an XML example for a response in OpenAPI 3

swagger-ui

openapi