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

或在响应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用户界面中目前是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使用相同的响应代码进行多个响应

1 个答案: