Question

我正在使用swagger-ui版本2.2.8

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

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

对于它产生的XML：

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

我的招摇模式是：

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

在swagger-ui中查看时，json模型看起来很好。然而，XML模型变为：

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

有没有办法防止这个双重＆lt; person＆gt;但仍然得到正确的JSON结果？

Answer 1

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

的JSON版本

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

将是

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

没有包装器属性person。

对于以这种方式不同的模型，您不能拥有单一模式。

您可以做的是将模型定义为自由格式对象（type: object而不是properties）并指定JSON / XML响应示例 - 但在这种情况下，您将失去定义对象属性的能力

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不能正确显示此类示例。

在下一个版本中 - OpenAPI 3.0（在撰写本文时为RC） - 可以为不同的响应MIME类型指定不同的模式。所以在3.0中你的例子将被描述为：

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

1 个答案: