Связаться с намиПодключиться

Валидация данных

Статья создана
Обновлена 5 сентября 2024 г.

Расширения x-yc-apigateway-validators и x-yc-apigateway-validator позволяют определить валидатор для следующих схем, описанных в спецификации API-шлюза внутри операции:

  • схема тела HTTP-запроса (поле content в Request Body Object);
  • схема параметров HTTP-запроса (поле schema в Parameter Object);
  • cхема тела HTTP-ответа (поле content в Response Object);
  • схема заголовков HTTP-ответа (поле schema в Header Object).

ValidatorObject

ValidatorObject или валидатор — набор параметров спецификации OpenAPI, который позволяет настроить валидацию HTTP-запросов и ответов API-шлюзом.

Параметры

В таблице ниже перечислены параметры объекта ValidatorObject.

Параметр Тип Обязательный Значение по-умолчанию Описание
validateRequestBody boolean Нет false Включить или выключить валидацию тела запроса.
validateRequestParameters boolean Нет false Включить или выключить валидацию параметров запроса.
validateResponseBody boolean Нет false Включить или выключить валидацию тела ответа.
validateResponseHeaders string Нет undefined Тип валидации заголовков ответа. Может принимать одно из следующих значений: any, superset, subset, exact.
validationErrorHandler ErrorHandler Нет undefined Обработчик ошибок валидации.

Типы валидации заголовков ответа

  • any — игнорируются отсутствующие или дополнительные заголовки ответа, проверяются только типы заголовков, перечисленных в спецификации.
  • superset — проверяется, что заголовки, перечисленные в спецификации, входят в список заголовков ответа.
  • subset — проверяется, что заголовки ответа входят в список заголовков, перечисленных в спецификации.
  • exact — проверяется, что список заголовков ответа полностью соответствует списку заголовков, перечисленных в спецификации.

Объект ErrorHandler

Содержит набор параметров, который позволяет передать ошибки валидации в интеграцию. Например, передать ошибки для обработки в функцию, контейнер, HTTP-интеграцию или вернуть объект из бакета.

Параметры

В таблице ниже перечислены параметры объекта ErrorHandler.

Параметр Тип Обязательный Описание
x-yc-apigateway-integration Расширение x-yc-apigateway-integration Да Интеграция, которая будет вызвана при ошибке валидации.
statusCode number Нет Код ответа, который будет возвращен пользователю вместе с ответом от интеграции.

Если интеграция из ErrorHandler вернет ответ с кодом 200, этот ответ отправится пользователю, который сделал запрос к API-шлюзу. Изменить код ответа, отправляемый пользователю, можно с помощью параметра statusCode в ErrorHandler.

Если интеграция из ErrorHandler вернет ошибку, пользователь увидит стандартное сообщение об ошибке валидации.

Объект ErrorHandlerEvent

Если при валидации API-шлюз обнаружил ошибку в запросе, он вызывает интеграцию, указанную в ErrorHandler. В эту интеграцию передается объект ErrorHandlerEvent с информацией об ошибке.

Параметры

В таблице ниже перечислены параметры объекта ErrorHandlerEvent.

Параметр Тип Описание
errorType string Возможные значения: response-body-validation-error, response-headers-validation-error, request-validation-error.
errorData ErrorObject[] Массив ошибок валидации.
statusCode number Код ошибки валидации.
path string Путь в спецификации OpenAPI.
request object Запрос, вызвавший ошибку.

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

Расширение x-yc-apigateway-validators позволяет описывать валидаторы в секции components. На определенные таким образом валидаторы можно ссылаться с помощью параметра $ref в расширении x-yc-apigateway-validator и подключать одни и те же валидаторы к разным операциям или ко всему API-шлюзу (см. параметр validator расширения x-yc-apigateway).

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

Расширение x-yc-apigateway-validator позволяет подключать валидатор к операции и имеет тип ValidatorObject.

Примеры спецификаций

Пример спецификации с валидацией URI или path-параметров HTTP-запроса

В данном примере валидация настроена для всех операций API-шлюза. Валидатор определяется на верхнем уровне через параметр validator расширения x-yc-apigateway.

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Petstore API

x-yc-apigateway:
  validator:
    validateRequestParameters: true

paths:
  /pets/{petId}:
    get:
      operationId: petById
      parameters:
        - in: path
          name: petId
          schema:
            type: integer
          required: true
          description: Pet identifier
      responses:
        '200':
          description: Pet
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pet"
      x-yc-apigateway-integration:
        type: cloud_functions
        function_id: b095c95icn**********

components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
        name:
          type: string

Пример спецификации с валидацией query-параметров HTTP-запроса

В данном примере валидатор вынесен в секцию components. Это позволяет ссылаться на один и тот же валидатор в разных операциях.

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Petstore API

paths:
  /pets:
    get:
      operationId: petsByIds
      parameters:
        - in: query
          name: ids
          style: form
          explode: false
          schema:
            type: array
            items:
              type: integer
              minItems: 1
      responses:
        '200':
          description: Pets
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"
      x-yc-apigateway-validator:
        $ref: "#/components/x-yc-apigateway-validators/request-params-validator"
      x-yc-apigateway-integration:
        type: cloud_functions
        function_id: b095c95icn**********

components:
  x-yc-apigateway-validators:
    request-params-validator:
      validateRequestParameters: true

  schemas:
    Pets:
      items:
        "$ref": "#/components/schemas/Pet"
      type: array
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
        name:
          type: string

Пример спецификации с валидацией заголовков HTTP-запроса и ответа

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Petstore API

x-yc-apigateway:
  validator:
    $ref: "#/components/x-yc-apigateway-validators/auth-validator"

paths:
  /users/me:
    get:
      operationId: myUserProfile
      parameters:
        - in: header
          name: Authorization
          schema:
            type: string
          required: true
          description: Authorization token
      responses:
        '200':
          description: User
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        '401':
          description: User
          headers:
            WWW-Authenticate:
              schema:
                type: string
              required: true
              description: Authentication scheme
      x-yc-apigateway-integration:
        type: cloud_functions
        function_id: b095c95icn**********

components:
  x-yc-apigateway-validators:
    auth-validator:
      validateRequestParameters: true
      validateResponseHeaders: superset

  schemas:
    User:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
        name:
          type: string

Пример спецификации с валидацией тела HTTP-запроса и ответа

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Petstore API

paths:
  /pets:
    post:
      operationId: creatPet
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Pet"
      responses:
        '200':
          description: Pet
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pet"
      x-yc-apigateway-validator:
        validateRequestBody: true
        validateResponseBody: true
      x-yc-apigateway-integration:
        type: cloud_functions
        function_id: b095c95icn**********

components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
        name:
          type: string

Пример спецификации с обработчиком ошибок

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

paths:
  /path-for-humans/{id}:
    get:
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: Numeric path parameter
      x-yc-apigateway-integration:
        type: dummy
        content:
          '*': Hello, World!
        http_code: 200
        http_headers:
          Content-Type: text/plain
      x-yc-apigateway-validator:
        validateRequestParameters: true
        validationErrorHandler:        
          x-yc-apigateway-integration:
            bucket: bucket
            type: object_storage
            object: error.html
          statusCode: 400
Предыдущая
Поддержка протокола WebSocket
Следующая
CORS