OpenAPI 3.0如何定义同时含属性与内容的XML标签适配Swagger UI

解决方法 #

你需要通过xml.text: true配置专门存储标签文本内容的字段，正确的Schema配置如下：

components:
  schemas:
    Filter:
      type: object
      xml:
        name: filter # 显式指定XML根标签名
      properties:
        # 属性字段
        id:
          type: string
          example: id001
          xml:
            attribute: true
        attr1:
          type: string
          example: admin
          xml:
            attribute: true
        # 标签文本内容字段
        value:
          type: string
          example: Administrator
          xml:
            text: true # 标记该字段值为XML标签的文本内容

配置后Swagger UI生成的XML就会符合你的预期：

<filter id="id001" attr1="admin">Administrator</filter>

错误原因说明 #

• 第一种配置错误是因为你直接给Filter对象设置了字符串类型的example，相当于把整个对象覆盖为纯文本，所以定义的属性全部失效。
• 第二种配置错误是因为没有定义存储标签文本内容的字段，所以生成的标签只有属性没有内部文本。

注意事项 #

请确保你使用的Swagger UI版本不低于3.38.0，旧版本对xml.text属性的支持存在缺陷。

内容的提问来源于stack exchange，提问作者Salem Hussein