如何大摇大摆地引用响应对象？答案

【问题标题】：How to reference to a response object with swagger?如何大摇大摆地引用响应对象？
【发布时间】：2015-07-06 15:29:38
【问题描述】：

我可以这样做：

parameters:
  avatarSizeParam:
    name: size
    in: query
    description: Size of avatar.
    enum: [32, 64]
    required: false
    type: integer
    format: int32

paths:
  /my/path/avatar:
    get:
      parameters:
        - $ref: '#/parameters/avatarSizeParam'

很好。 Swagger 定义了一个 parameters 键，您可以将 Parameter Objects 定义为重复使用。它还定义了一个responses 键，您可以在其中定义Response Objects 喜欢所以：

responses:
  notFoundResponse:
    description: Entity not found.
    schema:
      $ref: '#/definitions/schema404'

所以我假设我可以将之前的路径定义扩展到以下内容

paths:
  /my/path/avatar:
    get:
      parameters:
        - $ref: '#/parameters/avatarSizeParam'
      responses:
        - $ref: '#/responses/notFound'

但这似乎不起作用。我回到the spec 寻找Operations Object 并注意到parameters 可以是参考对象，但responses 不能。

如果允许响应定义对象（最顶层的responses）有什么意义你不能参考那里的项目？有办法吗？

【问题讨论】：

标签： api swagger

【解决方案1】：

如果看到here，则必须将HTTP状态码定义为key，那么正确的语法是：

paths:
  /my/path/avatar:
    get:
      parameters:
        - $ref: '#/parameters/avatarSizeParam'
      responses:
        404:
          $ref: '#/responses/notFound'

【讨论】：

谢谢！是的，这很有意义。忘了responses 是一个对象而不是一个数组哈哈