Question

我正在使用Swagger 2.0开发API的定义/文档优先规范。我设法将大多数可重用的组件分解为定义部分但是我无法弄清楚如何为常量数组创建可重用的定义。

例如，我有一些将返回图像的路径，如下所示：

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

哪个工作正常，但我希望能够为＆＃34;生成＆＃34;定义一个可重用的值数组。元素，以便我可以为将产生图像的任何路径重用相同的列表。

以下似乎是直观的方法，但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锚点来达到类似的效果。请注意，必须在使用锚之前定义锚，因此您需要将列表放在路径定义之上。

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）防止＆＃34;未使用的定义＆＃34;在Swagger编辑器中发出警告。

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

在swagger中创建可重用的数组定义

1 个答案: