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

Question

我正在使用 Swagger Hub 生成 API 并希望为获取请求获得多个响应：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 parts 示例（例如各个数组项的值）。换句话说，示例值不能从部分 $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'

或者在响应 schema:

旁边添加 example

          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 中是 not displayed。）

          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
          ...

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

Swagger OAS3.0 Multiple responses in the same response code

swagger

swagger-editor