大摇大摆地创建可重用的数组定义

Question

我正在使用 Swagger 2.0 制定 API 的 definition/documentation-first 规范。我已经设法将大多数可重用组件分解到定义部分，但是我无法弄清楚如何为常量数组创建可重用定义。

例如，我有几个路径可以 return 图片，比如这个：

paths:
  /resource/{imageId}:
    get:
      produces:
        - image/jpeg
        - image/png
        - image/gif
      parameters: 
        - in: path
          name: imageId
          type: string
          required: true
      responses: 
        200:
          description: Success
          schema:
            type: file

效果很好，但我希望能够为 "produces" 元素定义一个可重复使用的值数组，这样我就可以为将生成图像的任何路径重复使用相同的列表。

以下似乎是直观的方法，但 swagger 报告 imageMimeTypes 的定义无效：

paths:
  /resource/{imageId}:
    get:
      produces:
        $ref: "#/definitions/imageMimeTypes"
      parameters: 
        - in: path
          name: imageId
          type: string
          required: true
      responses: 
        200:
          description: Success
          schema:
            type: file
definitions:
  imageMimeTypes:
    - image/jpeg
    - image/png
    - image/gif

是否可以为这样的数组创建定义？如果是这样，应该使用什么语法？

Answer 1

首先，如果这些 produces 值在 大多数 操作中使用，您可以将它们定义为全局 produces 并在需要的地方覆盖。

produces:
  - image/jpeg
  - image/png
  - image/gif

paths:
  /resource/{imageId}:
    get:
      # Inherits global "produces"
      ...
  /something:
    get:
      # Overrides global "produces"
      produces:
        - application/json
      ...

您的第二个示例无效，因为 produces 不能有 $ref 值。但是您可以使用 YAML 锚点来实现类似的效果。注意anchor在使用前必须先定义，所以需要把list放在path定义上面

x-types:
  imageMimeTypes: &IMAGE-MIME-TYPES
    - image/jpeg
    - image/png
    - image/gif

paths:
  /resource/{imageId}:
    get:
      produces: *IMAGE-MIME-TYPES
      parameters: 
        - in: path
          name: imageId
          type: string
          required: true
      responses: 
        200:
          description: Success
          schema:
            type: file

我将列表放在扩展键 x-types 而不是 definitions 下 1) 因为 definitions 用于输入和输出模型而不是随机列表，以及 2) 防止Swagger 编辑器中的 "unused definition" 警告。

这适用于（至少）Swagger Editor 和 Swagger UI。

大摇大摆地创建可重用的数组定义

Creating reusable array definitions in swagger

arrays

yaml

swagger

swagger-2.0