Política OASValidation

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

Consulta la documentación de Apigee Edge.

Acerca de la política OASValidation

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

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

Añade una especificación de OpenAPI como recurso a un paquete de proxy de API mediante la interfaz de usuario o la API, tal como se describe en Gestionar recursos.

Esta política 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 de 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 del mensaje de solicitud que valida la política OASValidation por componente.

Componentes	Solicitar validación
Ruta base	Valida la ruta base definida por el proxy de API e ignora la ruta base especificada en la especificación de OpenAPI.
Ruta	Valida que la ruta de la solicitud (sin la ruta base) coincida con uno de los patrones de ruta definidos en la especificación de OpenAPI.
Verbo	Valida que el verbo se haya definido 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. Valida de forma opcional 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 con <ValidateMessageBody>. Nota: La política valida el cuerpo de un mensaje de solicitud con la especificación OpenAPI solo si el encabezado Content-Type se ha definido como application/json. Si el tipo de contenido no es application/json, la validación del cuerpo del mensaje de la solicitud se realizará automáticamente (sin validar el contenido).
Parámetros	Valida que los parámetros obligatorios estén presentes en la solicitud, incluidos los parámetros de ruta, encabezado, consulta y cookie. Valida que los valores de los parámetros coincidan con los definidos en la especificación de OpenAPI. Opcionalmente, valida si hay parámetros en la solicitud que no están definidos en la especificación de OpenAPI. Configura esta opción con <AllowUnspecifiedParameters>.

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

Componentes	Validación de respuestas
Ruta	Valida que la ruta de la solicitud (sin la ruta base) coincida con uno de los patrones de ruta definidos en la especificación de OpenAPI.
Verbo	Valida que el verbo se haya definido 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 de 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. Opcionalmente, 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 con <ValidateMessageBody>.

Nota: La política OASValidation de Apigee valida las rutas de solicitud y respuesta de forma diferente.
En la validación de solicitudes, se valida la ruta de la solicitud del proxy de API (por ejemplo, /hello para https://<BasePath>/hello).
En la validación de respuestas, se valida la ruta del endpoint de destino al que llama Apigee (por ejemplo, /apigee/hello para https://{target-basepath}}/apigee/hello).
Es fundamental conocer esta diferencia si las rutas del proxy y del destino son distintas, ya que debes alinear tu especificación de OpenAPI en consecuencia para validar las respuestas.

Ejemplos

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

Validar el mensaje de solicitud

En el siguiente ejemplo, la política myoaspolicy valida el cuerpo del mensaje de solicitud con el esquema del cuerpo del mensaje de solicitud de la operación definido en la especificación 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 la especificación de OpenAPI, se devuelve un error policies.oasvalidation.Failed.

Validar parámetros

En el siguiente ejemplo se configura la política para que falle si se especifica en la solicitud un parámetro de encabezado, de consulta o de cookie que no esté definido 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 que aparece más abajo.
¿Es obligatorio?	Obligatorio
Tipo	Objeto complejo
Elemento principal	n/a
Elementos secundarios	<DisplayName> <OASResource> <Source> <Options> <Source>

Sintaxis

El elemento <OASValidation> utiliza 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 muestran los ajustes predeterminados al añadir una política de validación de OAS a tu flujo en la interfaz de usuario 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	Predeterminado	¿Es 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. Opcionalmente, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.
continueOnError	falso	Opcional	Asigna el valor false para devolver un error cuando falle una política. Este es el comportamiento esperado de la mayoría de las políticas. Asigna el valor true para que la ejecución del flujo continúe incluso después de que falle una política. Consulta también: Las reglas de errores solo se activan cuando hay un error (sobre continueOnError) Gestionar fallos en el flujo actual
enabled	true	Opcional	Asigna el valor true para aplicar la política. Selecciona false para desactivar la política. La política no se aplicará aunque siga adjunta a un flujo.
async	falso	Obsoleto	Este atributo está obsoleto.

Referencia de elemento secundario

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

<DisplayName>

Se usa junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de usuario de gestión con un nombre diferente que suene más natural.

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

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

El elemento <DisplayName> utiliza 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 con la que se va a validar. Puedes almacenar este archivo:

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

Consulta más información en el artículo sobre cómo gestionar recursos.

Puedes especificar la especificación de OpenAPI mediante una plantilla de mensaje, 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 cadena de carga útil en el tiempo de ejecución. Para obtener más información, consulta Plantillas de mensajes.

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

Sintaxis

El elemento <OASResource> utiliza 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 del 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 OASValidation especifica un <OASResource> con requisitos de seguridad definidos a nivel global, no se aplican los requisitos de seguridad. Para asegurar el cumplimiento, todos los requisitos de seguridad deben definirse a nivel de operación 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.

<Opciones>

Configura las opciones de la política.

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

Sintaxis

El elemento <Options> utiliza 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 de la política. A continuación se describe cada una de las opciones con más detalle.

<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 con el esquema del cuerpo de la solicitud de la operación en la especificación de OpenAPI. Definir como true para validar el contenido del cuerpo del mensaje. Asigna el valor false para validar solo que existe el cuerpo del mensaje.

Puede controlar si la ejecución del flujo continúa después de un error de validación configurando el atributo continueOnError del elemento <OASValidation> en true.

Nota: La política valida el cuerpo de un mensaje de solicitud con la especificación OpenAPI solo si el encabezado Content-Type se ha definido como application/json. Si el tipo de contenido no es application/json, la validación del cuerpo del mensaje de la solicitud se realizará automáticamente (sin validar el contenido).

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

Sintaxis

El elemento <ValidateMessageBody> utiliza 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, de consulta o de cookie en la solicitud que no estén definidos 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> utiliza 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 especifica en la solicitud un parámetro de encabezado, de consulta o de cookie que no esté definido 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 en la solicitud que no están definidos en la especificación de OpenAPI.

Para permitir que se especifiquen en la solicitud parámetros de encabezado que no estén definidos en la especificación de OpenAPI, defina este parámetro como true. De lo contrario, asigne el valor false a este parámetro para que se produzca un error en 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> utiliza 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 en la solicitud un parámetro de encabezado que no esté definido 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 consulta en la solicitud que no están definidos en la especificación de OpenAPI.

Para permitir que se especifiquen en la solicitud parámetros de consulta que no estén definidos en la especificación de OpenAPI, defina este parámetro como true. De lo contrario, asigne el valor false a este parámetro para que se produzca un error en 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> utiliza 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 consulta 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 cookies en la solicitud que no están definidos en la especificación de OpenAPI.

Para permitir que se especifiquen en la solicitud parámetros de cookies que no estén definidos en la especificación de OpenAPI, asigne el valor true a este parámetro. De lo contrario, asigne el valor false a este parámetro para que se produzca un error en 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> utiliza 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 consulta 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 va a evaluar en función de los ataques de carga útil de JSON. Lo más habitual es que se defina como request, ya que normalmente tendrás que evaluar las solicitudes entrantes de las aplicaciones cliente. Defínelo como response para evaluar los mensajes de respuesta. Asigna el valor message para evaluar automáticamente el mensaje de solicitud cuando la política se adjunte al flujo de solicitud y el mensaje de respuesta cuando la política se adjunte al flujo de respuesta.

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

Sintaxis

El elemento <Source> utiliza 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 respuestas:

<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

Cada tipo de política se define mediante un esquema XML (.xsd). Puedes consultar los esquemas de políticas en GitHub.

Códigos de error

En esta sección se describen los códigos de error y los mensajes de error que devuelve Apigee, así como las variables de error que define, cuando esta política activa un error. Es importante que conozcas esta información si vas a desarrollar reglas de errores para gestionarlos. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo gestionar los fallos.

Errores de tiempo de ejecución

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

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

Errores de implementación

Estos errores pueden producirse al implementar un proxy que contenga 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 OpenAPI incluida en la implementación contiene errores que impiden que se compile. Por lo general, esto indica que la especificación no es una especificación OpenAPI 3.0 bien formada.
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 ha especificado correctamente.

Variables de error

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

Variable	Descripción	Ejemplo
fault.category	Categoría del fallo. Cuando la política rechaza una solicitud, siempre tendrá el valor Step.	fault.category = "Step"
fault.name	Nombre del fallo, tal como se indica en la tabla Errores de tiempo de ejecución de arriba. El nombre del error es la última parte del código de error.	fault.name Matches "ResourceDoesNotExist"
fault.reason	El motivo del error. Es una cadena legible por humanos que explica el motivo del error.	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 del fallo. Cuando la política rechaza una solicitud, siempre tendrá el valor OASValidationFailure.	fault.subcategory = "OASValidationFailure"
OASValidation.policy_name.failed	policy_name es el nombre de la política especificado por el usuario que ha provocado el error.	OASValidation.myoaspolicy.failed = true

Funciones de especificaciones de OpenAPI admitidas

La política OASValidation admite las funciones de la especificación OpenAPI que se resumen en la siguiente tabla, por categoría. También se indican las funciones 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 superará la validación de las funciones no admitidas y se producirá un error en la implementación del proxy de API.

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	binario byte contraseña
Objeto Discriminator	mapping propertyName	N/A
Objeto de tipo de contenido	schema	encoding example examples
Objeto de operaciones	parámetros requestBody responses security (compatibilidad parcial)	callbacks obsoleto servidores
Objeto Parameters	allowEmptyValue in (query, header, path) required responses schema style (deepObject, form, formmatrix, label, pipeDelimited, simple, spaceDelimited) Nota: deepObject solo admite parámetros de cadena. No admite matrices ni objetos anidados.	allowReserved deprecated example examples content
Objeto Paths	delete get head options parameters patch post put trace variables	servidores
Objeto del cuerpo de la solicitud	application/json application/hal+json application/x-www-form-urlencoded (no se admite el objeto encoding) content required	application/xml multipart/form-data text/plain text/xml
Objeto de respuesta	application/json application/hal+json application/x-www-form-urlencoded (no se admite el objeto encoding) content headers	application/xml links text/plain text/xml
Objeto Responses	default 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	obsoleto ejemplo solo lectura solo escritura xml
Objeto de esquema de seguridad	en (header, query) (se ignora si type es http) name type (apiKey, http)	bearerFormat flows openIdConnectUrl scheme
Objeto de servidor	url variables	Varias definiciones de servidor

Usar patrones en los esquemas

El estándar de la especificación OpenAPI permite que las especificaciones estipulen un schema para describir el tipo de datos de un parámetro o un campo. En el caso de los parámetros o campos de tipo cadena, el esquema también puede definir un pattern, que es una expresión regular (regex) que define las formas válidas de la cadena.

Por ejemplo, considere el siguiente fragmento de 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, en la operación getProduct, el parámetro product-id cumpla la expresión regular dada, que estipula una secuencia de 3 caracteres de palabra, un guion y 4 dígitos decimales.

La especificación de OpenAPI se remite al estándar de validación de esquemas JSON para definir formalmente el comportamiento del patrón al validar el valor de la cadena, y al estándar principal de esquemas JSON para obtener recomendaciones para los autores de esquemas sobre el conjunto restringido de sintaxis de expresiones regulares. Este último estándar recomienda evitar el uso de lookarounds (lookaheads y lookbehinds), referencias inversas y expresiones de caracteres octales, entre otras funciones, en los patrones de los documentos de la especificación de OpenAPI.

De forma predeterminada, Apigee valida el documento de especificación de OpenAPI al que hace referencia la política OASValidation e informa de los errores si el documento de especificación no tiene un formato correcto. Apigee también valida los patrones de expresiones regulares en el documento de especificación e informa de los problemas que encuentra.

Es importante tener en cuenta que, si utiliza funciones de expresiones regulares fuera del subconjunto recomendado, Apigee no validará la expresión regular y suspenderá cualquier validación adicional de su documento de especificación de OpenAPI. Si hay un error en el documento o en la expresión regular que usa una función que no pertenece al subconjunto recomendado, o si el tiempo de ejecución de Apigee no admite la función de expresión regular, el error se detectará solo en el tiempo de ejecución cuando se ejecute la política.

En la siguiente tabla se muestran algunos ejemplos.

Patrón	Comportamiento
^\w{3}-\d{4}$	El patrón es válido. Solo usa funciones de expresiones regulares del subconjunto recomendado. Apigee permitirá guardar o importar el proxy y, en el tiempo de ejecución, la política OASValidation funcionará según lo previsto, validando el parámetro con el 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 expresiones regulares fuera del subconjunto recomendado. Apigee informará de este error cuando importe o guarde su 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á de este error cuando guardes o importes tu proxy de API, ya que la expresión regular usa una búsqueda hacia delante negativa, que está fuera del subconjunto recomendado de funciones de expresiones regulares. El error solo se detectará 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 una búsqueda hacia delante negativa, que está fuera del subconjunto recomendado de funciones de expresiones regulares. Apigee suspenderá la validación del documento de especificación de OpenAPI. En el tiempo de ejecución, cuando ejecutes la política OASValidation que hace referencia a una especificación mediante este patrón, Apigee aplicará correctamente esta expresión regular para validar el valor del parámetro, ya que el tiempo de ejecución de Apigee admite lookaheads negativos.
^(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 expresiones regulares. Apigee suspenderá la validación del documento de especificación de OpenAPI. En el tiempo de ejecución, cuando ejecute la política OASValidation que hace referencia a una especificación que usa este patrón, Apigee devolverá un error porque el tiempo de ejecución de Apigee no admite esta función de regex.

Te recomendamos que uses solo el subconjunto de funciones recomendado en tu expresión regular para evitar errores de tiempo de ejecución.

Temas relacionados

• JSON Threat Protection policy
• Política SOAPMessageValidation