Política OASValidation

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Información sobre la política OASValidation

La política OASValidation (Validación de especificaciones de OpenAPI) te permite validar un mensaje de solicitud o respuesta entrante con una especificación de OpenAPI 3.0, con JSON o YAML. Consulta ¿Qué contenido se valida?

La política OASValidation especifica el nombre de la especificación de OpenAPI que se usará para la validación cuando se ejecute el paso en el que se adjunta la política. La Especificación de OpenAPI se almacena como un recurso en la siguiente ubicación estándar dentro del paquete del proxy de API: apiproxy/resources/oas. El documento de la Especificación de OpenAPI debe tener una extensión .json, .yml o .yaml.

Agrega una especificación de OpenAPI como un recurso a un paquete de proxy de API mediante la IU o la API, como se describe en Administra recursos.

Esta es una política estándar y se puede implementar en cualquier tipo de entorno. Para obtener información sobre los tipos de políticas y la disponibilidad con cada tipo de entorno, consulta Tipos de políticas.

Nota: Solo puedes almacenar la Especificación de OpenAPI con la revisión del proxy de API. Consulta Dónde se almacenan los recursos.

¿Qué contenido se valida?

En la siguiente tabla, se resume el contenido de los mensajes de solicitud que valida la política OASValidation por componente.

Componentes	Validación de la solicitud
Basepath	Valida la basepath definida por el proxy de API, ignora la basepath especificada en la Especificación de OpenAPI.
Ruta	Valida que la ruta de solicitud (menos la basepath) coincida con uno de los patrones de ruta definidos en la Especificación de OpenAPI.
Verbo	Valida que el verbo se define para la ruta en la Especificación de OpenAPI.
Cuerpo del mensaje de solicitud	Valida la existencia del cuerpo del mensaje en la solicitud, si es necesario. De forma opcional, valida el cuerpo del mensaje con el esquema del cuerpo de la solicitud de la operación en la Especificación de OpenAPI. Configura esta opción mediante <ValidateMessageBody> Nota: La política valida el cuerpo de un mensaje de solicitud respecto de la especificación de OpenAPI solo si el tipo de contenido se configura en application/json. Si el tipo de contenido no se configura como application/json, la validación del cuerpo del mensaje de solicitud se completará correctamente de forma automática (sin validar el contenido en realidad).
Parámetros	Verifica que los parámetros obligatorios estén presentes en la solicitud, incluidos parámetros de cookie, ruta, encabezado y consulta. Valida que los valores de parámetros coincidan con los definidos en la Especificación de OpenAPI. De forma opcional, valida si existen parámetros en la solicitud que no están definidos en la Especificación de OpenAPI. Configura esta opción mediante <AllowUnspecifiedParameters>

En la siguiente tabla, se resume el contenido de los mensajes de respuesta que valida la política OASValidation por componente.

Componentes	Validación de respuesta
Ruta	Valida que la ruta de solicitud (menos la basepath) coincida con uno de los patrones de ruta definidos en la Especificación de OpenAPI.
Verbo	Valida que el verbo se define para la ruta en la Especificación de OpenAPI.
Cuerpo del mensaje de respuesta	Valida la existencia del cuerpo del mensaje en la respuesta, si es necesario. Valida que los encabezados de respuesta en la especificación de OpenAPI estén presentes en el mensaje de respuesta y que el valor de los encabezados de respuesta coincida con el esquema. De forma opcional, valida el cuerpo del mensaje con el esquema del cuerpo de respuesta de la operación en la Especificación de OpenAPI. Configura esta opción mediante <ValidateMessageBody>

Ejemplos

En los siguientes ejemplos, se muestran algunas de las formas en las que puedes usar la política OASValidation para validar mensajes con una Especificación de OpenAPI 3.0.

Valida mensajes de solicitud

En el siguiente ejemplo, la política myoaspolicy valida el cuerpo del mensaje de solicitud en el esquema de cuerpo de mensaje de solicitud de la operación definido en la Especificación de OpenAPI my-spec.json.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.json</OASResource>
   <Options>
      <ValidateMessageBody>true</ValidateMessageBody>
   </Options>
   <Source>request</Source>
</OASValidation>

Si el cuerpo del mensaje no cumple con la especificación de OpenAPI, se muestra un error policies.oasvalidation.Failed.

Valida parámetros

En el siguiente ejemplo, se configura la política para que falle si se especifican parámetros de encabezado, consulta o cookie en la solicitud que no se definen en la especificación de OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

Elemento <OASValidation>

Define la política de validación de la especificación de OpenAPI.

Valor predeterminado	Consulta la pestaña Política predeterminada, a continuación
¿Es obligatorio?	Obligatorio
Tipo	Objeto complejo
Elemento principal	No disponible
Elementos secundarios	<DisplayName> <OASResource> <Source> <Options> <Source>

Sintaxis

El elemento <OASValidation> usa la siguiente sintaxis:

<OASValidation
  continueOnError="[true|false]"
  enabled="[true|false]"
  name="policy_name"
>
    <!-- All OASValidation child elements are optional except OASResource -->
    <DisplayName>policy_display_name</DisplayName>
    <OASResource>validation_JSON_or_YAML</OASResource>
    <Options>
        <ValidateMessageBody>[true|false]</ValidateMessageBody>
        <AllowUnspecifiedParameters>
            <Header>[true|false]</Header>
            <Query>[true|false]</Query>
            <Cookie>[true|false]</Cookie>
        </AllowUnspecifiedParameters>
    </Options>
    <Source>message_to_validate</Source>
</OASValidation>

Política predeterminada

En el siguiente ejemplo, se muestra la configuración predeterminada cuando agregas una política de validación de OAS a tu flujo en la IU de Apigee:

<OASValidation continueOnError="false" enabled="true" name="OpenAPI-Spec-Validation-1">
    <DisplayName>OpenAPI Spec Validation-1</DisplayName>
    <Properties/>
    <Source>request</Source>
    <OASResource>oas://OpenAPI-Spec-Validation-1.yaml</OASResource>
</OASValidation>

Este elemento tiene los siguientes atributos que son comunes a todas las políticas:

Atributo	Predeterminada	(obligatorio)	Descripción
name	N/A	Obligatorio	El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres. De forma opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.
continueOnError	falso	Opcional	Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas. Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle. También consulta: Las reglas de fallas se activan SOLAMENTE en un estado de error (sobre el continueOnError) Controla fallas dentro del flujo actual
enabled	true	Opcional	Configúralo como true para aplicar la política. Configúralo como false para desactivar la política. La política no se aplicará, incluso si permanece conectada a un flujo.
async	falso	Obsoleta	Este atributo dejó de estar disponible.

Referencia del elemento secundario

En esta sección, se describen los elementos secundarios de <OASValidation>.

<DisplayName>

Se usan además del atributo name para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

El elemento <DisplayName> es común a todas las políticas.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional. Si omites <DisplayName>, se usa el valor del atributo name de la política.
Tipo	String
Elemento principal	<PolicyElement>
Elementos secundarios	Ninguno

El elemento <DisplayName> usa la siguiente sintaxis:

Sintaxis

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Ejemplo

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

El elemento <DisplayName> no tiene atributos ni elementos secundarios.

<OASResource>

Especifica la especificación de OpenAPI que se va a validar. Puedes almacenar este archivo:

• En el alcance del proxy de API en /apiproxy/resources/oas, en el paquete del proxy de API
• En la sección Resources de la vista del navegador del editor de proxy de API.

Para obtener más información, consulta Administra recursos.

Puedes precisar la especificación de OpenAPI con una plantilla de mensajes, como {oas.resource.url}. En este caso, el valor de la variable de flujo oas.resource.url (entre llaves) se evaluará y se sustituirá en la string de carga útil en el entorno de ejecución. Para obtener más información, consulta Plantillas de mensajes.

Valor predeterminado	None
¿Es obligatorio?	Obligatorio
Tipo	String
Elemento principal	<OASValidation>
Elementos secundarios	Ninguno

Sintaxis

El elemento <OASResource> usa la siguiente sintaxis:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   ...
</OASValidation>

Ejemplo

En el siguiente ejemplo, se hace referencia a la especificación my-spec.yaml que se almacena en /apiproxy/resources/oas en el paquete de proxy de API:

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
</OASValidation>

El elemento <OASResource> no tiene atributos ni elementos secundarios.

Nota: Si la política de OASValidation especifica un <OASResource> con requisitos de seguridad establecidos a nivel global, no se aplican los requisitos de seguridad. Para garantizar la aplicación forzosa, todos los requisitos de seguridad deben establecerse en el nivel de operation en la especificación de OpenAPI que se pasa en el elemento <OASResource> de esta política. Para obtener más información, consulta Problemas conocidos de Apigee

.

<Options>

Configura las opciones para la política.

Valor predeterminado	n/a
¿Es obligatorio?	Opcional
Tipo	Tipo complejo
Elemento principal	<OASValidation>
Elementos secundarios	<ValidateMessageBody> <AllowUnspecifiedParameters>

Sintaxis

El elemento <Options> usa la siguiente sintaxis:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <ValidateMessageBody>[true|false]</ValidateMessageBody>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
         <Query>[true|false]</Query>
         <Cookie>[true|false]</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Ejemplo

En el siguiente ejemplo, se configuran las opciones para la política. Cada una de las opciones se describe con más detalle a continuación.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <ValidateMessageBody>false</ValidateMessageBody>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<ValidateMessageBody>

Especifica si la política debe validar el cuerpo del mensaje en el esquema de cuerpo de la solicitud de la operación en la Especificación de OpenAPI. Configúralo como true para validar el contenido del cuerpo del mensaje. Se configura en false para validar solo que el cuerpo del mensaje exista.

Puedes controlar si la ejecución del flujo continúa siguiendo un error de validación si configuras el atributo continueOnError del elemento <OASValidation> en true.

Nota: La política valida el cuerpo de un mensaje de solicitud respecto de la especificación de OpenAPI solo si el tipo de contenido se configura en application/json. Si el tipo de contenido no se configura como application/json, la validación del cuerpo del mensaje de solicitud se completará correctamente de forma automática (sin validar el contenido realmente).

Valor predeterminado	false
¿Es obligatorio?	Opcional
Tipo	Booleano
Elemento principal	<Options>
Elementos secundarios	Ninguno

Sintaxis

El elemento <ValidateMessageBody> usa la siguiente sintaxis:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
         <ValidateMessageBody>[true|false]</ValidateMessageBody>
   </Options>
   ...
</OASValidation>

Ejemplo

En el siguiente ejemplo, se habilita la validación del contenido del cuerpo del mensaje:

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <ValidateMessageBody>true</ValidateMessageBody>
   </Options>
</OASValidation>

<AllowUnspecifiedParameters>

Configura el comportamiento de la política si hay parámetros de encabezado, consulta o cookie presentes en la solicitud que no se definen en la Especificación de OpenAPI.

Valor predeterminado	n/a
¿Es obligatorio?	Opcional
Tipo	Tipo complejo
Elemento principal	<Options>
Elementos secundarios	<Header> <Query> <Cookie>

Sintaxis

El elemento <AllowUnspecifiedParameters> usa la siguiente sintaxis:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
         <Query>[true|false]</Query>
         <Cookie>[true|false]</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Ejemplo

En el siguiente ejemplo, se configura la política para que falle si se especifican parámetros de encabezado, consulta o cookie en la solicitud que no se definen en la especificación de OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Header> (elemento secundario de <AllowUnspecifiedParameters>)

Configura el comportamiento de la política si hay parámetros de encabezado presentes en la solicitud que no se definen en la Especificación de OpenAPI.

Para permitir que se especifiquen parámetros de encabezado en la solicitud que no se definen en la Especificación de OpenAPI, configura este parámetro en true. De lo contrario, establece este parámetro en false para que falle la ejecución de la política.

Valor predeterminado	true
¿Es obligatorio?	Booleano
Tipo	Tipo complejo
Elemento principal	<AllowUnspecifiedParameters>
Elementos secundarios	Ninguno

Sintaxis

El elemento <Header> usa la siguiente sintaxis:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Ejemplo

En el siguiente ejemplo, se configura la política para que falle si se especifica un parámetro de encabezado en la solicitud que no se define en la Especificación de OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Query> (elemento secundario de <AllowUnspecifiedParameters>)

Configura el comportamiento de la política si hay parámetros de búsqueda presentes en la solicitud que no se definen en la Especificación de OpenAPI.

Para permitir que los parámetros de búsqueda se especifiquen en la solicitud que no están definidos en la Especificación de OpenAPI, configura este parámetro en true. De lo contrario, establece este parámetro en false para que falle la ejecución de la política.

Valor predeterminado	true
¿Es obligatorio?	Booleano
Tipo	Tipo complejo
Elemento principal	<AllowUnspecifiedParameters>
Elementos secundarios	Ninguno

Sintaxis

El elemento <Query> usa la siguiente sintaxis:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Ejemplo

En el siguiente ejemplo, se configura la política para que falle si se especifica un parámetro de búsqueda en la solicitud que no está definido en la Especificación de OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>false</Query>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Cookie> (elemento secundario de <AllowUnspecifiedParameters>)

Configura el comportamiento de la política si hay parámetros de cookie presentes en la solicitud que no se definen en la Especificación de OpenAPI.

Para permitir que los parámetros de cookies se especifiquen en la solicitud que no se definen en la Especificación de OpenAPI, configura este parámetro en true. De lo contrario, establece este parámetro en false para que falle la ejecución de la política.

Valor predeterminado	true
¿Es obligatorio?	Booleano
Tipo	Tipo complejo
Elemento principal	<AllowUnspecifiedParameters>
Elementos secundarios	Ninguno

Sintaxis

El elemento <Cookie> usa la siguiente sintaxis:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Ejemplo

En el siguiente ejemplo, se configura la política para que falle si se especifica un parámetro de búsqueda en la solicitud que no está definido en la Especificación de OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Source>

Mensaje JSON que se evaluará en relación con los ataques de carga útil JSON. Normalmente, este se configura como request, ya que, por lo general, deberás evaluar las solicitudes entrantes de las apps de cliente. Configúralo como respuesta para evaluar los mensajes de respuesta. Configúralo como mensaje para evaluar automáticamente el mensaje de solicitud cuando la política se adjunta al flujo de solicitudes y el mensaje de respuesta cuando la política está adjunta al flujo de respuesta.

Valor predeterminado	solicitud
¿Es obligatorio?	Opcional
Tipo	String
Elemento principal	<Source>
Elementos secundarios	Ninguno

Sintaxis

El elemento <Source> usa la siguiente sintaxis:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Source>[message|request|response]</Source>
   ...
</OASValidation>

Ejemplo

En el siguiente ejemplo, se evalúa automáticamente el mensaje de solicitud cuando la política se adjunta al flujo de solicitudes y el mensaje de respuesta cuando la política se adjunta al flujo de respuesta:

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Source>message</Source>
</OASValidation>

El elemento <Source> no tiene atributos ni elementos secundarios.

Esquema de esta política

Un esquema XML (.xsd) define cada tipo de política. Como referencia, los esquemas de políticas están disponibles en GitHub.

Códigos de error

En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo solucionar fallas.

Errores de entorno de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Código de falla	Estado de HTTP	Causa
steps.oasvalidation.Failed	400	El cuerpo del mensaje de solicitud no se puede validar en la especificación de OpenAPI proporcionada.
steps.oasvalidation.Failed	500	El cuerpo del mensaje de solicitud no se puede validar en la especificación de OpenAPI proporcionada.
steps.oasvalidation.SourceMessageNotAvailable	500	La variable especificada en el elemento <Source> de la política está fuera del alcance o no se puede resolver.
steps.oasvalidation.NonMessageVariable	500	El elemento <Source> se establece en una variable que no es del tipo mensaje.

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.

Nombre del error	Causa
ResourceDoesNotExist	La especificación de OpenAPI a la que se hace referencia en el elemento <OASResource> no existe.
ResourceCompileFailed	La especificación de OpenAPI que se incluye en la implementación contiene errores que evitan que se compile. Por lo general, esto indica que la especificación no es una especificación 3.0 de OpenAPI con el formato correcto.
BadResourceURL	No se puede procesar la especificación de OpenAPI a la que se hace referencia en el elemento <OASResource>. Esto puede ocurrir si el archivo no es un archivo JSON o YAML, o si la URL del archivo no se especificó de forma correcta.

Variables con fallas

Estas variables se configuran cuando esta política activa un error en el entorno de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

Variable	Descripción	Ejemplo
fault.category	La categoría de la falla. Cuando la política rechaza una solicitud, siempre se aplicará Step.	fault.category = "Step"
fault.name	El nombre de la falla como se indica en la tabla de Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla.	fault.name Matches "ResourceDoesNotExist"
fault.reason	El motivo de la falla. Es una string legible que explica el motivo de la falla.	OASValidation OAS-1 with resource "oas://my-spec1.yaml": failed with reason: "[ERROR - POST operation not allowed on path '/persons/13'.: []]"
fault.subcategory	La subcategoría de la falla. Cuando la política rechace una solicitud, siempre se conservará OASValidationFailure.	fault.subcategory = "OASValidationFailure"
OASValidation.policy_name.failed	policy_name es el nombre especificado por el usuario de la política que generó la falla.	OASValidation.myoaspolicy.failed = true

Características de las especificaciones de OpenAPI admitidas

La política OASValidation admite las funciones de especificación de OpenAPI que se resumen en la siguiente tabla, por categoría. También se enumeran las características que no se admiten.

Nota: La política OASValidation rechazará las especificaciones de OpenAPI que usen funciones no admitidas. En este caso, la política no pasará la validación de las funciones no compatibles y la implementación del proxy de API fallará.

Categoría	Compatible	No compatible
Formatos de tipos de datos	boolean date date-time double email float int32/int64 ipv4/ipv6 md5 sha1/sha256/sha512 string uri uri-template uuid	binary byte password
Objeto discriminante	mapping propertyName	N/A
Objeto de tipo de medio	schema	encoding example examples
Objeto de operaciones	parameters requestBody responses security (partial support)	callbacks deprecated servers
Objeto de parámetros	allowEmptyValue in (query, header, path) required responses schema style (deepObject, form, formmatrix, label, pipeDelimited, simple, spaceDelimited) Nota: deepObject solo admite parámetros de string. No se admiten arreglos ni objetos anidados.	allowReserved deprecated example examples content
Objeto de rutas	delete get head options parameters patch post put trace variables	servidores
Objeto de cuerpo de solicitud	application/json application/hal+json application/x-www-form-urlencoded (objeto encoding no admitido) content required	application/xml multipart/form-data text/plain text/xml
Objeto de respuesta	application/json application/hal+json application/x-www-form-urlencoded (objetoencoding no admitido) content headers	application/xml links text/plain text/xml
Objeto de respuestas	predeterminado Código de estado HTTP	N/A
Objeto de esquema	$ref additionalProperties (solo variante de marca booleana) allOf (se ignora si additionalProperties es false) anyOf enum exclusiveMaximum/exclusiveMinimum format items maximum/minimum maxItems/minItems maxLength/minLength maxProperties/minProperties multipleOf not nullable oneOf pattern properties required title type uniqueItems	deprecated example readOnly writeOnly xml
Objeto de esquema de seguridad	in (header, query) (se ignora si type es http) name type (apiKey, http)	bearerFormat flows openIdConnectUrl scheme
Objeto del servidor	url variables	Definiciones de varios servidores

Usa patrones en el esquema

El estándar de la Especificación de OpenAPI permite que las especificaciones establezcan un schema para describir el tipo de datos de un parámetro o campo. Para un parámetro o campo de tipo cadena, el esquema también puede definir un pattern, que es una expresión regular (regex) que define los formularios válidos para la cadena.

A modo de ejemplo, considera el siguiente fragmento de la especificación de OpenAPI:

paths:
  /products/{product-id}:
    get:
      operationId: getProduct
      summary: Get product by id
      description: returns information regarding a product, by id
      parameters:
        - name: product-id
          in: path
          description: id of the product
          required: true
          schema:
            type: string
            pattern: '^\w{3}-\d{4}$'

Esta especificación requiere que, para la operación getProduct, el parámetro product-id cumpla con la regex proporcionada, que estipula una secuencia de 3 caracteres de palabra, un guion y 4 dígitos decimales.

La especificación de OpenAPI aplaza a el estándar de validación de esquemas JSON para definir formalmente el comportamiento del patrón en la validación del valor de cadena y al estándar principal de esquemas JSON para las recomendaciones a los autores de esquemas sobre el conjunto restringido de sintaxis de expresiones regulares. Este último estándar recomienda evitar el uso de búsquedas (lookaheads y lookbehinds), referencias cruzadas y expresiones de caracteres octal, entre otras funciones, dentro de los patrones de los documentos de la especificación de OpenAPI.

De forma predeterminada, Apigee valida el documento de la especificación de OpenAPI al que hace referencia la política OASValidation y, si el documento de especificación no tiene el formato correcto, informa errores. Apigee también valida los patrones de regex en tu documento de especificaciones y, además, informa los problemas que se encuentran allí.

Es importante tener en cuenta que, si empleas funciones de regex fuera del subconjunto recomendado, Apigee no validará la regex y suspenderá cualquier validación adicional de tu documento de especificación de OpenAPI. Si hay un error en el documento o en la regex que usa una función fuera del subconjunto recomendado, o si el entorno de ejecución de Apigee no admite la función de regex, el error se detectará solo durante el tiempo de ejecución cuando se ejecute la política.

En la siguiente tabla, se proporcionan algunos ejemplos.

Patrón	Comportamiento
^\w{3}-\d{4}$	El patrón es válido. Solo usa funciones de regex dentro del subconjunto recomendado. Apigee permitirá guardar o importar el proxy y, durante el tiempo de ejecución, la política OASValidation funcionará según lo previsto y validará el parámetro en función del patrón.
^([a-z]\w{3}-\d{4}$	El patrón no es válido, ya que le falta un paréntesis de cierre. El patrón no usa funciones de regex fuera del subconjunto recomendado. Apigee informará este error cuando importes o guardes tu proxy de API.
^(?![a-z]\w{3}-\d{4}$	El patrón no es válido. Al igual que en el ejemplo anterior, falta un paréntesis de cierre. Sin embargo, Apigee no informará este error cuando guardes o importes tu proxy de API, porque la regex usa una búsqueda anticipada negativa, que está fuera del subconjunto recomendado de funciones de regex. El error se detectará solo en el tiempo de ejecución cuando se ejecute la política.
^(?![a-z])\w{3}-\d{4}$	El patrón es válido, pero usa un análisis anticipado negativo, que está fuera del subconjunto recomendado de funciones de regex. Apigee suspenderá la validación del documento de la especificación de OpenAPI. En el entorno de ejecución, cuando ejecutes la política OASValidation que hace referencia a una especificación con este patrón, debido a que el entorno de ejecución de Apigee admite búsquedas anticipadas negativas, Apigee aplicará correctamente esta regex para validar el valor del parámetro.
^(a)?b(?(1)c|d)$	El patrón es válido, pero usa una condición de grupo de captura, que está fuera del subconjunto recomendado de funciones de regex. Apigee suspenderá la validación del documento de la especificación de OpenAPI. En el entorno de ejecución, cuando ejecutes la política OASValidation que hace referencia a una especificación con este patrón, Apigee mostrará un error porque el entorno de ejecución de Apigee no admite esta función de regex.

Te recomendamos que uses solo el subconjunto recomendado de funciones en tu regex para evitar fallas en el tiempo de ejecución.

Temas relacionados

• Política de protección contra amenazas de JSON
• Política SOAPMessageValidation