如何在 swagger 中提供 XML 参数示例

我在用Swashbuckle 5.6.0 and Swashbuckle.Examples.3.5.1记录 WebApi2 项目。我有一个使用 XML 正文并返回文本响应的操作。我希望文档包含 XML 输入的示例 - 例如<SampleXml><!-- example XML --></SampleXml>.

我的招摇输出如下，除了为了这个问题的目的，我添加了内容类型application/json to the comsumes财产。事实上，我只想让application/xml and text/xml.

当我用 Swagger 查看此内容时，我看到：

• 当参数内容类型application/xml被选中后，我会得到一个带有我的模型名称的生成的 XML 示例，即<XmlModel></XmlModel>.

• 当参数内容类型application/json被选中，我得到了我想要的示例输入<SampleXml><!-- example XML --></SampleXml>.

如何在参数内容类型时获取示例输入application/xml被选中？

{
  "swagger": "2.0",
  "info": {
    "version": "v1",
    "title": "Sample"
  },
  "host": "localhost:63434",
  "schemes": [
    "http"
  ],
  "paths": {
    "/sampleXml/": {
      "post": {
        "tags": [
          "xmlSample"
        ],
        "summary": "XML sample.",
        "description": "Post XML sample",
        "operationId": "Xml_Post",
        "consumes": [
          "application/xml",
          "application/json",
          "text/xml",
        ],
        "produces": [
          "text/plain"
        ],
        "parameters": [
          {
            "name": "xmlContent",
            "in": "body",
            "description": "The content of the XML document.",
            "required": true,
            "schema": {
              "$ref": "#/definitions/XmlModel"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "type": "string"
            }
          },
        }
      }
    }
  },
  "definitions": {
    "XmlModel": {
      "type": "object",
      "properties": {},
      "example": "<SampleXml><!-- example XML --></SampleXml>"
    }
  }
}

更改根 XML 标记<XmlModel> to <SampleXml>, add xml.name https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#user-content-xmlName到您的架构定义：

  "definitions": {
    "XmlModel": {
      "type": "object",
      "xml": {
         "name": "SampleXml"
      }
    }
  }

这将在 Swagger UI 中生成以下示例 XML：

<?xml version="1.0" encoding="UTF-8"?>
<SampleXml>
</SampleXml>

如果添加属性定义：

  "definitions": {
    "XmlModel": {
      "type": "object",
      "xml": {
         "name": "SampleXml"
      },
      "properties": {
        "id": {
          "type": "integer",
          "example": 7,
          "xml": {
            "attribute": true
          }
        },
        "foo": {
          "type": "string",
          "example": "bar"
        }
      }
    }
  }

您的 XML 示例将包含相应的元素：

<?xml version="1.0" encoding="UTF-8"?>
<SampleXml id="7">
    <foo>bar</foo>
</SampleXml>

但是，如果您想要文字字符串<SampleXml><!-- example XML --></SampleXml>含有一个<!-- comment -->，据我所知这是不可能的。

Update:Swagger UI 仅支持在响应示例中使用文字 XML 字符串：

"responses": {
  "200": {
    "description": "OK",
    "schema": {
      "type": "string"
    },
    "examples": {
      "application/xml": "<SampleXml><!-- example XML --></SampleXml>"
    }
  }
}

但不在请求正文示例中。