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 規范目前似乎不支持這種情況。 但是您仍然可以通過以下方式實現此結果：

• 使用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>