Расширения спецификации API Gateway. Обзор

Расширение x-yc-apigatewayРасширение x-yc-apigateway

Расширение x-yc-apigateway позволяет задать верхнеуровневые параметры API-шлюза, значения которых будут наследоваться вложенными расширениями.

Поддерживаемые параметрыПоддерживаемые параметры

В таблице ниже перечислены параметры, специфичные для API-шлюза сервиса API Gateway. Описание остальных параметров читайте в спецификации OpenAPI 3.0.

Спецификация расширенияСпецификация расширения

x-yc-apigateway:
  service_account_id: <идентификатор_сервисного_аккаунта>
  validator: <ValidatorObject_или_ссылка_на_него>
  cors: <CorsRuleObject_или_ссылка_на_него>
  rateLimit: <RateLimitObject_или_ссылка_на_него>
  ignoreTrailingSlashes: <true_или_false>
  smartWebSecurity:
    securityProfileId: <идентификатор_профиля_безопасности>

Расширение x-yc-apigateway-integrationРасширение x-yc-apigateway-integration

Расширение x-yc-apigateway-integration — это точка входа для интеграции API-шлюза с другими сервисами.

Поддерживаемые параметрыПоддерживаемые параметры

В таблице ниже перечислены параметры, специфичные для API-шлюза сервиса API Gateway. Описание остальных параметров читайте в спецификации OpenAPI 3.0.

Спецификация расширенияСпецификация расширения

<запрос>:
  <метод>:
    x-yc-apigateway-integration:
      type: <тип>
      <список параметров в виде пары ключ: значение>

Содержимое расширения меняется в зависимости от указанного типа (type) в блоке x-yc-apigateway-integration:

• dummy — возвращает фиксированное содержимое с указанным кодом ответа и необходимыми заголовками без участия стороннего сервиса.
• cloud_functions — вызывает указанную функцию, передавая ей на вход информацию об HTTP-запросе, и возвращает клиенту результат выполнения этой функции.
• http — перенаправляет запрос в указанный URL.
• object_storage — передает обработку запроса в Object Storage с целью раздачи статических файлов.
• cloud_datasphere — вызывает указанную ноду DataSphere, передавая ей тело запроса со значениями входных переменных, и возвращает результат выполнения ноды в теле ответа.
• cloud_datastreams — обращается к Yandex Data Streams для выполнения операции с указанным потоком.
• serverless_containers — перенаправляет запрос в указанный контейнер.
• cloud_ymq — обращается к Yandex Message Queue для выполнения операции с указанной очередью.
• cloud_ydb — обращается к Yandex Managed Service for YDB для выполнения операции с указанной документной таблицей.

Все типы поддерживают подстановку параметров — замену всех ключей на соответствующее значение. Ключ должен быть определен как параметр соответствующей операции (допускаются все типы параметров, определенные в OpenAPI-Specification — path, query, header, cookie).
Подстановка параметров производится только в некоторых значениях, в зависимости от типа расширения.

Расширение components:x-yc-apigateway-integrationsРасширение components:x-yc-apigateway-integrations

Расширение x-yc-apigateway-integrations позволяет указывать интеграцию в стандартной секции components. На определенные таким образом интеграции можно ссылаться с помощью параметра $ref в расширении x-yc-apigateway-integration.

Спецификация расширенияСпецификация расширения

Пример спецификации расширения:

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0

x-yc-apigateway:
  variables:
    handler:
      default: "#/components/x-yc-apigateway-integrations/BaseGetDefault"
      enum:
        - "#/components/x-yc-apigateway-integrations/BaseGetDefault"
        - "#/components/x-yc-apigateway-integrations/BaseGetUnimplemented"

paths:
  /:
    get:
      x-yc-apigateway-integration:
        $ref: "${var.handler}"

components:
  x-yc-apigateway-integrations:
    BaseGetDefault:
      type: cloud_functions
      function_id: b095c95icnvb********
      tag: "$latest"
      service_account_id: ajehfe84hhl********
    BaseGetUnimplemented:
      type: dummy
      content:
        '*': Sorry, endpoint is not implemented yet.
      http_code: 501
      http_headers:
        Content-Type: text/plain

Расширение x-yc-status-mappingРасширение x-yc-status-mapping

Расширение x-yc-status-mapping позволяет заменить код ответа в интеграции.

Спецификация расширенияСпецификация расширения

paths:
  /:
    <метод>:
      responses:
        <код_ответа>:
          description: ""
          content:
            ...
          x-yc-status-mapping: <новый_код_ответа>
      ...

Расширение x-yc-schema-mappingРасширение x-yc-schema-mapping

Расширение x-yc-schema-mapping позволяет преобразовывать JSON-тело запроса к интеграции или ответа от нее.

Спецификация расширенияСпецификация расширения

x-yc-schema-mapping:
 type:static
 template:
   <название_поля>: "<значение_поля>"
   ...