Блог

У меня есть конечная точка, определенная в моем API, которая принимает параметр path.

Допустимые значения для этого параметра уже выражены в виде перечисления, которое я определил как компонент схемы и использовал в ответе.

Два вопроса:

1. Если вы можете просто использовать ссылку на этот компонент схемы в качестве параметра, зачем вообще настраивать выделенные компоненты параметров вместо использования общего компонента схемы, который вы можете повторно использовать где угодно?
2. Если вы должны использовать параметры вместо общих схем, можете ли вы создать компонент параметров, который ссылается на компонент схемы? Я не могу найти никакого синтаксиса для этого, который прошел бы проверку.

Я бы вставил свои определения сюда, но я не могу найти ни одного варианта форматирования, который не создавал бы ужасный беспорядок.

Если вы можете просто использовать ссылку на этот компонент схемы в качестве параметра, зачем вообще настраивать выделенные компоненты параметров вместо использования общего компонента схемы, который вы можете повторно использовать где угодно?

Определения параметров имеют дополнительные атрибуты, отсутствующие в схемах, такие как расположение параметра в запросе ( in: path in: query , и т.д.), метод сериализации значений массива и объекта и другие. A schema -это всего лишь один из атрибутов параметра, но сама по себе схема не предоставляет достаточной информации для эффективного описания параметра.

можете ли вы создать компонент параметров, который ссылается на компонент схемы?

ДА. Параметры имеют schema , это может быть встроенная схема или $ref :

 paths:
  /something/{role}:
    get:
      parameters:
        - $ref: '#/components/parameters/role'
...

components:
  parameters:
    role:
      in: path
      name: role
      required: true
      schema:
        $ref: '#/components/schemas/UserRole'  # <-----

  schemas:
    UserRole:
      type: string
      enum: [user, admin]