Swagger OAS3.0 Несколько ответов в одном коде ответа - PullRequest
Новая
       7

Swagger OAS3.0 Несколько ответов в одном коде ответа

0 голосов
/ 28 ноября 2018

Я использую 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"
}]

Спасибо, Шаши

1 Ответ

0 голосов
/ 28 ноября 2018

Таким образом, ваш ответ представляет собой массив объектов, и вы хотите указать ответ 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.) 

          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 it.Обратите внимание, что мы можем $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
          ...
...