如何防止 Swagger-ui 中的 xml-wrapper 元素 [英] How to prevent xml-wrapper element in Swagger-ui

问题描述

我使用的是 swagger-ui 版本 2.2.8

I am using swagger-ui version 2.2.8

我们现有的 API 可以生成 application/json 以及 application/xml.
对于 json 中的单个记录结果，它会生成:

Our existing API can produce application/json as well as application/xml.
For a single record result in json it produces:

{
  "person": {
    "id": 23,
    "name": "John"
  }
}

对于它产生的 XML:

and for XML it produces:

<person>
  <id>23</id>
  <name>John</name>
</person>

我的招摇模式是:

 {
    "person": {
        "type": "object",
        "properties": {
            "person": {
                "$ref": "#/definitions/personfields"
            }
        }
    }
}

在 swagger-ui 中查看时，json 模型看起来不错.但是 XML 模型变成了:

When viewed in swagger-ui the json model is looking fine. However the XML-model becomes:

<person>
  <person>
    <id>1</id>
    <name>string</name>
  </person>
</person>

有没有办法防止这种双重<person>但仍然得到正确的 JSON 结果?

Is there a way to prevent this double <person> but still get the correct JSON result?

推荐答案

在 OpenAPI 术语中，您的 JSON 和 XML 模型是不同的 –

In OpenAPI terms, your JSON and XML models are different – the JSON version of

<person>
  <id>23</id>
  <name>John</name>
</person>

会

{
  "id": 23,
  "name": "John"
}

没有包装器属性person.

对于以这种方式不同的模型，您不能有一个单一的架构.

You can't have a single schema for models that differ in this way.

你可以做的是将你的模型定义为一个自由形式的对象(type: object 没有 properties)并指定 JSON/XML 响应示例而不是–但在这种情况下，您将无法定义对象属性.

What you can do is define your model as a free-form object (type: object without properties) and specify the JSON/XML response examples instead – but in this case you lose the ability to define the object properties.

definitions:
  person:
    type: object

paths:
  /person:
    get:
      produces:
        - application/json
        - application/xml
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/person'
          examples:
            application/json: |
              {
                "person": {
                  "id": 23,
                  "name": "John"
                }
              }
            application/xml: |
              <person>
                <id>23</id>
                <name>John</name>
              </person>              

注意:如果您使用 Swagger UI，请使用 3.0.x 版本，因为 2.2.x 无法正确显示此类示例.

Note: If you use Swagger UI, use version 3.0.x becase 2.2.x does not display such examples correctly.

在下一个版本中–OpenAPI 3.0(在撰写本文时为 RC)–可以为不同的响应 MIME 类型指定不同的模式.因此，在 3.0 中，您的示例将被描述为:

In the next version – OpenAPI 3.0 (which is RC at the moment of writing) – it will be possible to specify different schemas for different response MIME types. So in 3.0 your example will be described as:

paths:
  /person:
    get:
      responses:
        '200':
          description: OK
          content: 
            application/json:
               $ref: '#/components/definitions/PersonJson'               
            application/xml:
               $ref: '#/components/definitions/Person'

components:
  definitions:

    # XML object schema
    Person:
      type: object
      properties:
        id:
          type: integer
          example: 23
        name:
          type: string
          example: John
      xml:
        name: person

    # JSON object schema with a wrapper property "person"
    PersonJson:
      type: object
      properties:
        person:
          $ref: '#/components/definitions/Person'

这篇关于如何防止 Swagger-ui 中的 xml-wrapper 元素的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！