Question

这里招摇的新手。我已经完成了swagger primer，据我所知，下面的例子应该可行。

我的响应类型只是不同结构的数组（这些结构在全局定义部分中定义，以减少膨胀，因为它们可能是嵌套的，因此可以重用）。

这是我的定义：

consumes:
  - application/json
produces:
  - application/json
schemes:
  - http
swagger: '2.0'
[...Additional details excluded...]

paths:
  /first:
    get:
      responses:
        '200':
          $ref: '#/responses/response1'
  /second:
    get:
      responses:
        '200':
          $ref: '#/responses/response2'


definitions:
  ObjectA:
    type: object
    properties:
      listOfObjBs:
        type: array
        items:
          $ref: '#/definitions/ObjectB'
  ObjectB:
    type: object
    properties:
      listOfObjCs:
        type: array
        items:
          $ref: '#/definitions/ObjectC'
  ObjectC:
    description: A build
    type: object
    properties:
      someNumericData:
        type: integer
        format: int64

responses:
  response1:
    description: There are 2 types of responses, this is the first kind.
    schema:
      type: object
    headers:
      data: 
        type: array
        items:
          $ref: '#/definitions/ObjectA'
  response2:
    description: This is the second kind.
    schema:
      type: object
    headers:
      data:
        type: array
        items:
          $ref: '#/definitions/ObjectC'

但是，我在swagger网页编辑器中遇到了验证问题。

响应中的模式错误['response1']。headers ['data']。items应该   没有其他propertiesadditionalProperty：$ ref

respond.response1.headers.data.items。$ ref items中的语义错误   $ refs无法满足以下任何条件：“＃/ definitions ”，   “＃/参数”

响应中的模式错误['response2']。headers ['data']。items应该   没有其他属性additionalProperty：$ ref

respond.response2.headers.data.items。$ ref items中的语义错误   $ refs无法满足以下任何条件：“＃/ definitions ”，   “＃/参数”

看起来我正在错误地使用json引用，但我不确定原因。

我还尝试将response1和response2放在定义部分并直接引用它们（例如将$ ref直接指向'＃/ definitions / response1'而不是'＃/ responses / response1'）。但是我从编辑那里得到一个错误，说我不能直接引用定义。

构建此定义的正确方法是什么？

Answer 1

身体的回复有schema。要引用模型定义，请使用$ref引用作为schema：

的值

responses:
  response1:  # <--- This node is on the same level as the status codes '200'/'404' etc.
    description: There are 2 types of responses, this is the first kind.
    schema:
      $ref: '#/definitions/ObjectA'

      # Or if the response is an array:
      # type: array
      # items:
      #   $ref: '#/definitions/ObjectA'


  response2:
    description: This is the second kind.
    schema:
      $ref: '#/definitions/ObjectC'

示例中的错误是将引用放在headers下。 headers部分定义了响应的HTTP标头，例如X-RateLimit或Set-Cookie，而不是实际的主体有效负载。

  response1:
    description: There are 2 types of responses, this is the first kind.
    schema:
      type: object

    # Errors were caused by this
    headers:
      data: 
        type: array
        items:
          $ref: '#/definitions/ObjectA'

Swagger语法：如何从可重用的响应中引用模型定义

1 个答案: