Question

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

我的招摇输出在下面，但为了这个问题的目的，我已将内容类型application/json添加到comsumes属性。实际上，我只想允许application/xml和text/xml。

当我用Swagger查看时，我看到了：

当选择参数内容类型application/xml时，我会获得一个生成的XML示例，其中包含我的模型名称，即<XmlModel></XmlModel>。
选择参数内容类型application/json后，我会获得所需的示例输入<SampleXml></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>"
    }
  }
}

Answer 1

要将根XML标记从<XmlModel>更改为<SampleXml>，请将xml.name添加到架构定义中：

  "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></SampleXml>包含，那么AFAIK就不可能。

更新：Swagger UI仅支持在回复示例中使用文字XML字符串：

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

但不在请求正文示例中。

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

1 个答案: