Swagger OAS3.0 同一响应代码中的多个响应

Question

我正在使用 Swagger Hub 生成 API，并希望获得 get 请求的多个响应：https://virtserver.swaggerhub.com/factly/test/1.0.0/categories

以下是我定义 API 的方式。当我执行 API 时，我只得到一个类别的响应。如何将所有三个类别定义为响应？任何帮助是极大的赞赏。

openapi: 3.0.0
info:
  description: This is the sample API for Core
  version: "1.0.0"
  title: Dega Core API
tags:
  - name: Core
    description: Operations related to Core
paths:
  /categories:
    get:
      tags:
        - Core
      summary: gets all the categories
      description: this is to get all the available categories
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryItem'
              examples:
                category1:
                  $ref: '#/components/examples/category1'
                category2:
                  $ref: '#/components/examples/category2' 
                category3:
                  $ref: '#/components/examples/category3'
components:
  schemas:
    CategoryItem:
      type: object
      required:
        - id
        - name
        - slug
        - createdDate
      properties:
        id:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
        name:
          type: string
          example: Category 1
        slug:
          type: string
          example: category-1
        description:
          type: string
          example: This is a sample category
        parent:
          type: string
          example: null
        createdDate:
          type: string
          format: date-time
          example: '2016-08-29T09:12:33.001Z'
  examples:
    category1:
      value:
        id: d290f1ee-6c54-4b01-90e6-d701748f0851
        name: Category 1
        slug: category-1
        description: This is the sample description for Category 1
        parent: null
        createdDate: '2016-08-29T09:12:33.001Z'
    category2:
      value:
        id: d290f1ee-6c54-4b01-90e6-d701748f0851
        name: Category 2
        slug: category-2
        description: This is the sample description for Category 2
        parent: null
        createdDate: '2016-08-29T09:12:33.001Z'
    category3:
      value:
        id: d290f1ee-6c54-4b01-90e6-d701748f0851
        name: Category 3
        slug: category-3
        description: This is the sample description for Category 3
        parent: d290f1ee-6c54-4b01-90e6-d701748f0851
        createdDate: '2016-08-29T09:12:33.001Z'
servers:
  - url: 'https://virtserver.swaggerhub.com/factly/test/1.0.0'

我期待的答复如下：

[{
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "name": "Category 1",
    "slug": "category-1",
    "description": "This is the sample description for Category 1",
    "createdDate": "2016-08-29T09:12:33.001Z"
},
{
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "name": "Category 2",
    "slug": "category-2",
    "description": "This is the sample description for Category 2",
    "createdDate": "2016-08-29T09:12:33.001Z"
},
{
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "name": "Category 3",
    "slug": "category-3",
    "description": "This is the sample description for Category 3",
    "parent": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "createdDate": "2016-08-29T09:12:33.001Z"
}]

谢谢，沙希

Answer 1

因此，您的响应是一个对象数组，并且您希望指定example包含具有多个项目的数组的响应。

有多种方法可以指定数组响应的示例，但在任何情况下，示例都必须是完整的示例，也就是说，您不能 $ref'erence示例的部分内容（例如各个数组项的值）。换句话说，示例值不能从部分 $refs 构建。

您可以将其放入example数组架构中type: array：

          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryItem'
                example:
                  - id: d290f1ee-6c54-4b01-90e6-d701748f0851
                    name: Category 1
                    slug: category-1
                    description: This is the sample description for Category 1
                    createdDate: '2016-08-29T09:12:33.001Z'
                  - id: d290f1ee-6c54-4b01-90e6-d701748f0851
                    name: Category 2
                    slug: category-2
                    description: This is the sample description for Category 2
                    createdDate: '2016-08-29T09:12:33.001Z'
                  - id: d290f1ee-6c54-4b01-90e6-d701748f0851
                    name: Category 3
                    slug: category-3
                    description: This is the sample description for Category 3
                    parent: d290f1ee-6c54-4b01-90e6-d701748f0851
                    createdDate: '2016-08-29T09:12:33.001Z'

example或者在响应旁边添加schema：

          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryItem'
              example:
                - id: d290f1ee-6c54-4b01-90e6-d701748f0851
                  name: Category 1
                  slug: category-1
                  description: This is the sample description for Category 1
                  createdDate: '2016-08-29T09:12:33.001Z'
                - id: d290f1ee-6c54-4b01-90e6-d701748f0851
                  ...

或者，如果您想指定示例的描述，请使用examples关键字（复数），如下所示。（但examples目前未显示在 Swagger UI 中。）

          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryItem'
              examples:
                categoryWithThreeItems:
                  summary: Example of a category with three items
                  value:
                    - id: d290f1ee-6c54-4b01-90e6-d701748f0851
                      name: Category 1
                      slug: category-1
                      description: This is the sample description for Category 1
                      createdDate: '2016-08-29T09:12:33.001Z'
                    - id: d290f1ee-6c54-4b01-90e6-d701748f0851
                      ...

或者将整个示例放入该components/example部分及其中$ref。再次注意，我们只能举出$ref整个例子，而不能举出例子的一部分。

          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryItem'
              examples:
                categoryWithThreeItems:
                  $ref: '#/components/examples/categoryWithThreeItems'
components:
  examples:
    categoryWithThreeItems:
      summary: Example of a category with three items
      value:
        - id: d290f1ee-6c54-4b01-90e6-d701748f0851
          name: Category 1
          slug: category-1
          description: This is the sample description for Category 1
          createdDate: '2016-08-29T09:12:33.001Z'
        - id: d290f1ee-6c54-4b01-90e6-d701748f0851
          ...