[Документация Yandex Cloud](../../../index.md) > [Yandex API Gateway](../../index.md) > [Концепции](../index.md) > Расширения спецификации > Обзор # Расширения спецификации API Gateway. Обзор ## Расширение x-yc-apigateway {#top-level} Расширение `x-yc-apigateway` позволяет задать верхнеуровневые параметры API-шлюза, значения которых будут наследоваться вложенными расширениями. ### Поддерживаемые параметры {#parameters} В таблице ниже перечислены параметры, специфичные для API-шлюза сервиса API Gateway. Описание остальных параметров читайте в [спецификации OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification). Параметр | Тип | Описание -------------------------|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------- `serviceAccountId` | `string` | Идентификатор [сервисного аккаунта](../../../iam/concepts/users/service-accounts.md), от имени которого API-шлюз будет выполнять операции. `validator` | `ValidatorObject` | [Валидатор HTTP-запросов и ответов](validator.md#validator_object) или ссылка на него. Может быть переопределен на уровне конкретной операции. `cors` | `CorsRuleObject` | [Правило обработки preflight-запросов CORS](cors.md#corsrule_object) или ссылка на него. Может быть переопределено на уровне конкретного пути. `rateLimit` | `RateLimitObject` | [Ограничение скорости обработки запросов](rate-limit.md#rate_limit_object) или ссылка на него. Может быть переопределено на уровне конкретного пути и/или операции. `ignoreTrailingSlashes` | `boolean` | Если установлено значение `true`, API Gateway игнорирует слеш (`/`) в конце URL запроса, иначе — учитывает его наличие или отсутствие при поиске обработчика в [OpenAPI-спецификации](../../../glossary/openapi.md). Значение по умолчанию — `true`. `securityProfileId` | `string` | Идентификатор [профиля безопасности](../../../smartwebsecurity/concepts/profiles.md) Smart Web Security. ### Спецификация расширения {#tl-spec} ```yaml x-yc-apigateway: service_account_id: <идентификатор_сервисного_аккаунта> validator: cors: rateLimit: ignoreTrailingSlashes: smartWebSecurity: securityProfileId: <идентификатор_профиля_безопасности> ``` ## Расширение x-yc-apigateway-integration {#integration} Расширение `x-yc-apigateway-integration` — это точка входа для интеграции API-шлюза с другими сервисами. ### Поддерживаемые параметры {#parameters} В таблице ниже перечислены параметры, специфичные для API-шлюза сервиса API Gateway. Описание остальных параметров читайте в [спецификации OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification). Параметр | Тип | Описание ----|----|---- `type` | `string` | Тип расширения. Доступные значения: `dummy`, `cloud_functions`, `http`, `object_storage`, `cloud_datasphere`, `cloud_datastreams`, `serverless_containers`, `cloud_ymq`, `cloud_ydb` и `swagger`. ### Спецификация расширения {#intg-spec} ``` <запрос>: <метод>: x-yc-apigateway-integration: type: <тип> <список параметров в виде пары ключ: значение> ``` Содержимое расширения меняется в зависимости от указанного типа (`type`) в блоке `x-yc-apigateway-integration`: * [dummy](dummy.md) — возвращает фиксированное содержимое с указанным кодом ответа и необходимыми заголовками без участия стороннего сервиса. * [cloud_functions](cloud-functions.md) — вызывает указанную функцию, передавая ей на вход информацию об HTTP-запросе, и возвращает клиенту результат выполнения этой функции. * [http](http.md) — перенаправляет запрос в указанный URL. * [object_storage](object-storage.md) — передает обработку запроса в Object Storage с целью раздачи статических файлов. * [cloud_datasphere](datasphere.md) — вызывает указанную ноду DataSphere, передавая ей тело запроса со значениями входных переменных, и возвращает результат выполнения ноды в теле ответа. * [cloud_datastreams](datastreams.md) — обращается к Yandex Data Streams для выполнения операции с указанным потоком. * [serverless_containers](containers.md) — перенаправляет запрос в указанный контейнер. * [cloud_ymq](ymq.md) — обращается к Yandex Message Queue для выполнения операции с указанной очередью. * [cloud_ydb](ydb.md) — обращается к Yandex Managed Service for YDB для выполнения операции с указанной [документной таблицей](../../../ydb/concepts/dynamodb-tables.md). * [swagger](swagger.md) — позволяет получать интерактивную документацию, а также тестировать и отлаживать API в интерфейсе Swagger UI. Все типы поддерживают подстановку параметров — замену всех ключей на соответствующее значение. Ключ должен быть определен как параметр соответствующей операции (допускаются все типы параметров, определенные в [OpenAPI-Specification](https://github.com/OAI/OpenAPI-Specification) — `path`, `query`, `header`, `cookie`). Подстановка параметров производится только в некоторых значениях, в зависимости от типа расширения. ## Расширение components:x-yc-apigateway-integrations {#integrations} Расширение `x-yc-apigateway-integrations` позволяет указывать интеграцию в стандартной секции [components](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#components-object). На определенные таким образом интеграции можно ссылаться с помощью параметра `$ref` в расширении `x-yc-apigateway-integration`. ### Спецификация расширения {#intg-spec} Пример спецификации расширения: ```yaml 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 {#status-mapping} Расширение [x-yc-status-mapping](status-mapping.md) позволяет заменить код ответа в интеграции. ### Спецификация расширения {#status-mapping-spec} ```json paths: /: <метод>: responses: <код_ответа>: description: "" content: ... x-yc-status-mapping: <новый_код_ответа> ... ``` ## Расширение x-yc-schema-mapping {#schema-mapping} Расширение [x-yc-schema-mapping](schema-mapping.md) позволяет преобразовывать JSON-тело запроса к интеграции или ответа от нее. ### Спецификация расширения {#schema-mapping-spec} ```json x-yc-schema-mapping: type:static template: <название_поля>: "<значение_поля>" ... ```