OpenAPI 3.0 - 描述具有属性和值的 OpenAPI 3.0 (Swagger 3.0) 对象中 XML 标记的对象的问题

Question

我无法让 Swagger UI 创建具有属性和内容（同时具有属性和值的对象）的适当 XML 标签：

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

相反，我得到了这个

<filter>Administrator</filter>

如果我使用这个模式

components:
  schemas:
    Filter:
      type: object
      example: Administrator
      properties:
        id:
          type: string
          example: id001
          xml:
            attribute: true
        attr1:
          type: string
          example: admin
          xml:
            attribute: true

或这个

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

如果我使用这个模式

components:
  schemas:
    Filter:
      type: object
      properties:
        id:
          type: string
          example: id001
          xml:
            attribute: true
        attr1:
          type: string
          example: admin
          xml:
            attribute: true

我尝试了很多方法来解决这个问题，但没有成功

Answer 1

正如 OpenAPI 规范 this scenario currently doesn't seem to be supported 所回答的那样。但您仍然可以通过以下方式获得此结果：

using a nested property 和 type: object（对我来说似乎很老套）
为您的 API 规格手动制作示例（见下文）

以下是如何在 content 部分下指定示例：

openapi: 3.0.0
info:
  version: 1.0.0
  title: Sample API
  description: A sample API to illustrate OpenAPI concepts

paths:
  /filters:
    get:
      responses:
        "200":
          description: filters
          content:
            application/xml:
              schema:
                $ref: "#/components/schemas/Filters"
              example: |
                <?xml version="1.0" encoding="UTF-8"?>
                <filters>
                  <filter id="id001" attr1="admin">Administrator</filter>
                </filters>

或者，如果您想重复使用示例，可以将它们放在 components 下并在方法的 examples 部分引用它们：

openapi: 3.0.0
info:
  version: 1.0.0
  title: Sample API
  description: A sample API to illustrate OpenAPI concepts

paths:
  /filters:
    get:
      responses:
        "200":
          description: filters
          content:
            application/xml:
              schema:
                $ref: "#/components/schemas/Filters"
              examples:
                Filters:
                  $ref: "#/components/examples/Filters"

components:
  schemas:
  # ...

  examples:
    Filters:
      value: |
        <?xml version="1.0" encoding="UTF-8"?>
        <filters>
          <filter id="id001" attr1="admin">Administrator</filter>
        </filters>

OpenAPI 3.0 - 描述具有属性和值的 OpenAPI 3.0 (Swagger 3.0) 对象中 XML 标记的对象的问题

OpenAPI 3.0 - Issue describing an object for XML tag in OpenAPI 3.0 (Swagger 3.0) objects that have both attributes and a value

xml

swagger

swagger-ui

swagger-editor

openapi