Règle OASValidation

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

À propos de la stratégie OASValidation

La règle OASValidation (validation de spécification OpenAPI) vous permet de valider une requête ou un message de réponse entrants par rapport à une spécification OpenAPI 3.0 (JSON ou YAML). Consultez la section Quels contenus sont validés ?

La stratégie OASValidation spécifie le nom de la spécification OpenAPI à utiliser pour la validation lorsque l'étape à laquelle la stratégie est associée s'exécute. La spécification OpenAPI est stockée en tant que ressource dans l'emplacement standard suivant dans le groupe de proxys d'API : apiproxy/resources/oas. Le document de spécification OpenAPI doit comporter l'extension .json, .yml ou .yaml.

Ajoutez une spécification OpenAPI en tant que ressource à un groupe de proxys d'API à l'aide de l'interface utilisateur ou de l'API, comme décrit dans Gérer les ressources.

Cette règle est une règle standard qui peut être déployée sur n'importe quel type d'environnement. Pour en savoir plus sur les types de règles et la disponibilité avec chaque type d'environnement, consultez la section Types de règles.

Remarque : Vous ne pouvez stocker la spécification OpenAPI qu'avec la révision du proxy d'API. Consultez la page Emplacement de stockage des ressources.

Quel contenu est validé ?

Le tableau suivant récapitule le contenu du message de requête validé par la règle OASValidation, par composant.

Composants	Validation de requête
Basepath	Valide le chemin de base défini par le proxy d'API ; ignore le chemin de base spécifié dans la spécification OpenAPI.
Chemin	Vérifie que le chemin de la requête (moins le chemin de base) correspond à l'un des formats de chemin d'accès définis dans la spécification OpenAPI.
Verbe	Vérifie que le verbe est défini pour le chemin d'accès dans la spécification OpenAPI.
Corps du message de la requête	Vérifie l'existence du corps du message dans la requête, si nécessaire. Le cas échéant, vérifie le corps du message par rapport au schéma de corps de la requête de l'opération dans la spécification OpenAPI. Configurer cette option à l'aide de <ValidateMessageBody> Remarque : La règle valide un corps de message de requête par rapport à la spécification OpenAPI uniquement si Type de contenu est défini sur application/json. Si le type de contenu n'est pas défini sur application/json, la validation du corps du message de requête est automatiquement effectuée (sans valider le contenu).
Paramètres	Vérifie que les paramètres requis sont présents dans la requête, y compris les paramètres de chemin, d'en-tête, de requête et de cookie. Vérifie que les valeurs des paramètres correspondent à celles définies dans la spécification OpenAPI. Le cas échéant, vérifie s'il existe dans la requête des paramètres qui ne sont pas définis dans la spécification OpenAPI. Configurer cette option à l'aide de <AllowUnspecifiedParameters>

Le tableau suivant récapitule le contenu du message de réponse confirmé par la règle OASValidation, par composant.

Composants	Validation de réponse
Chemin	Vérifie que le chemin de la requête (moins le chemin de base) correspond à l'un des formats de chemin d'accès définis dans la spécification OpenAPI.
Verbe	Vérifie que le verbe est défini pour le chemin d'accès dans la spécification OpenAPI.
Corps du message de la réponse	Vérifie l'existence du corps du message dans la réponse, si nécessaire. Vérifie que les en-têtes de réponse de la spécification OpenAPI sont présents dans le message de réponse, et que la valeur des en-têtes de réponse correspond au schéma. Le cas échéant, vérifie le corps du message par rapport au schéma de corps de la réponse de l'opération dans la spécification OpenAPI. Configurer cette option à l'aide de <ValidateMessageBody>

Exemples

Les exemples suivants montrent certaines manières d'utiliser la règle OASValidation pour valider les messages par rapport à une spécification OpenAPI 3.0.

Vérifier le message de requête

Dans l'exemple suivant, la règle myoaspolicy valide le corps du message de requête en fonction du schéma du corps du message de requête de l'opération défini dans la spécification OpenAPI my-spec.json.

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

Si le corps du message n'est pas conforme à la spécification OpenAPI, une erreur policies.oasvalidation.Failed est renvoyée.

Vérifier les paramètres

L'exemple suivant configure la règle pour qu'elle échoue si un paramètre d'en-tête, de requête ou de cookie est spécifié dans la requête mais pas dans la spécification OpenAPI.

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

Élément <OASValidation>

Définit la règle de validation de la spécification OpenAPI.

Valeur par défaut	Consultez l'onglet Règles par défaut ci-dessous.
Obligatoire ?	Obligatoire
Type	Objet complexe
Élément parent	Non disponible
Éléments enfants	<DisplayName> <OASResource> <Source> <Options> <Source>

Syntaxe

L'élément <OASValidation> utilise la syntaxe suivante :

<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>

Règle par défaut

L'exemple suivant montre les paramètres par défaut lorsque vous ajoutez une règle de validation OAS à votre flux dans l'interface utilisateur d'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>

Cet élément possède les attributs suivants qui sont communs à toutes les règles :

Attribut	Par défaut	Obligatoire ?	Description
name	ND	Obligatoire	Nom interne de la règle. La valeur de l'attribut name peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères. Vous pouvez également utiliser l'élément <DisplayName> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion avec un nom différent, en langage naturel.
continueOnError	faux	Facultatif	Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles. Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir aussi : Les règles d'erreur sont déclenchées UNIQUEMENT en cas d'erreur (à propos de continueOnError) Gérer les pannes dans le flux actuel
enabled	true	Facultatif	Définissez sur true pour appliquer la règle. Définissez sur false pour désactiver la règle. La règle ne sera pas appliquée même si elle reste associée à un flux.
async	faux	Obsolète	Cet attribut est obsolète.

Référence d'élément enfant

Cette section décrit les éléments enfants de <OASValidation>.

<DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent et plus naturel.

L'élément <DisplayName> est commun à toutes les règles.

Valeur par défaut	N/A
Obligatoire ?	Facultatif. Si vous omettez <DisplayName>, la valeur de l'attribut name de la règle est utilisée.
Type	Chaîne
Élément parent	<PolicyElement>
Éléments enfants	Aucun

L'élément <DisplayName> utilise la syntaxe suivante :

Syntaxe

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

Exemple

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

L'élément <DisplayName> ne comporte aucun attribut ni élément enfant.

<OASResource>

Spécifie la spécification OpenAPI par rapport à laquelle procéder à la validation. Vous pouvez stocker ce fichier :

• Au niveau du champ d'application de proxy d'API sous /apiproxy/resources/oas dans le groupe de proxys d'API
• Dans la section Resources de la vue du navigateur de l'éditeur de proxy d'API

Pour plus d'informations, consultez Gérer les ressources.

Vous pouvez spécifier la spécification OpenAPI à l'aide d'un modèle de message, tel que {oas.resource.url}. Dans ce cas, la valeur de la variable de flux oas.resource.url (entre accolades) est évaluée et remplacée par la chaîne de charge utile lors de l'exécution. Pour en savoir plus, consultez l'article Modèles de message.

Valeur par défaut	Aucune
Obligatoire ?	Obligatoire
Type	Chaîne
Élément parent	<OASValidation>
Éléments enfants	Aucun

Syntaxe

L'élément <OASResource> utilise la syntaxe suivante :

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

Exemple

L'exemple suivant fait référence à la spécification my-spec.yaml stockée sous /apiproxy/resources/oas dans le groupe de proxys d'API :

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

L'élément <OASResource> ne comporte aucun attribut ni élément enfant.

Remarque : Si la règle OASValidation spécifie une ressource <OASResource> avec des exigences de sécurité définies au niveau global, les exigences de sécurité ne sont pas appliquées. Pour garantir qu'elles le soient, toutes les exigences de sécurité doivent être définies au niveau de l'opération dans la spécification OpenAPI transmise dans l'élément <OASResource> de cette règle. Pour en savoir plus, consultez la section Problèmes connus liés à Apigee.

<Options>

Permet de configurer les options de la stratégie.

Valeur par défaut	N/A
Obligatoire ?	Facultatif
Type	Type complexe
Élément parent	<OASValidation>
Éléments enfants	<ValidateMessageBody> <AllowUnspecifiedParameters>

Syntaxe

L'élément <Options> utilise la syntaxe suivante :

<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>

Exemple

L'exemple suivant configure les options de la stratégie. Chacune des options est décrite plus en détail ci-dessous.

<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>

Spécifie si la stratégie doit valider le corps du message par rapport au schéma du corps de la requête de l'opération dans la spécification OpenAPI. Définissez la valeur sur true pour valider le contenu du corps du message. Définissez la valeur sur false pour confirmer que le corps du message existe.

Vous pouvez vérifier si l'exécution du flux continue après une erreur de validation en définissant l'attribut continueOnError de l'élément <OASValidation> sur true.

Remarque : La règle valide un corps de message de requête par rapport à la spécification OpenAPI uniquement si type de contenu est défini sur application/json. Si le type de contenu n'est pas défini sur application/json, la validation du corps du message de requête réussit automatiquement (sans valider le contenu).

Valeur par défaut	false
Obligatoire ?	Facultatif
Type	Booléen
Élément parent	<Options>
Éléments enfants	Aucun

Syntaxe

L'élément <ValidateMessageBody> utilise la syntaxe suivante :

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

Exemple

L'exemple suivant active la validation du contenu du corps du message :

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

<AllowUnspecifiedParameters>

Configure le comportement de la stratégie si des paramètres d'en-tête, de requête ou de cookie sont présents dans la requête et non définis dans la spécification OpenAPI.

Valeur par défaut	N/A
Obligatoire ?	Facultatif
Type	Type complexe
Élément parent	<Options>
Éléments enfants	<Header> <Query> <Cookie>

Syntaxe

L'élément <AllowUnspecifiedParameters> utilise la syntaxe suivante :

<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>

Exemple

L'exemple suivant configure la règle pour qu'elle échoue si un paramètre d'en-tête, de requête ou de cookie est spécifié dans la requête mais pas dans la spécification 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> (enfant de <AllowUnspecifiedParameters>)

Configure le comportement de la règle si la requête contient des paramètres de cookie qui ne sont pas définis dans la spécification OpenAPI.

Pour autoriser la spécification des paramètres d'en-tête dans la requête qui ne sont pas définis dans la spécification OpenAPI, définissez ce paramètre sur true. Sinon, définissez ce paramètre sur false pour que l'exécution de la stratégie échoue.

Valeur par défaut	true
Obligatoire ?	Booléen
Type	Type complexe
Élément parent	<AllowUnspecifiedParameters>
Éléments enfants	Aucun

Syntaxe

L'élément <Header> utilise la syntaxe suivante :

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

Exemple

L'exemple suivant configure la règle pour qu'elle échoue si un paramètre d'en-tête est spécifié dans la requête mais pas défini dans la spécification OpenAPI.

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

<Query> (enfant de <AllowUnspecifiedParameters>)

Configure le comportement de la règle si la requête contient des paramètres de requête qui ne sont pas définis dans la spécification OpenAPI.

Pour autoriser la spécification des paramètres de requête dans la requête qui ne sont pas définies dans la spécification OpenAPI, définissez ce paramètre sur true. Sinon, définissez ce paramètre sur false pour que l'exécution de la stratégie échoue.

Valeur par défaut	true
Obligatoire ?	Booléen
Type	Type complexe
Élément parent	<AllowUnspecifiedParameters>
Éléments enfants	Aucun

Syntaxe

L'élément <Query> utilise la syntaxe suivante :

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

Exemple

L'exemple suivant configure la règle pour qu'elle échoue si un paramètre de requête est spécifié dans la requête mais pas défini dans la spécification OpenAPI.

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

<Cookie> (enfant de <AllowUnspecifiedParameters>)

Configure le comportement de la règle si la requête contient des paramètres de cookie qui ne sont pas définis dans la spécification OpenAPI.

Pour autoriser la spécification des paramètres de cookies dans la requête qui ne sont pas définis dans la spécification OpenAPI, définissez ce paramètre sur true. Sinon, définissez ce paramètre sur false pour que l'exécution de la stratégie échoue.

Valeur par défaut	true
Obligatoire ?	Booléen
Type	Type complexe
Élément parent	<AllowUnspecifiedParameters>
Éléments enfants	Aucun

Syntaxe

L'élément <Cookie> utilise la syntaxe suivante :

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

Exemple

L'exemple suivant configure la règle pour qu'elle échoue si un paramètre de requête est spécifié dans la requête mais pas défini dans la spécification OpenAPI.

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

<Source>

Message JSON à évaluer par rapport aux attaques contre les charges utiles JSON. Ce paramètre est habituellement défini sur request, car vous devez généralement évaluer les requêtes entrantes provenant des applications clientes. Définissez la valeur sur response pour évaluer les messages de réponse. Définissez la valeur sur message pour évaluer automatiquement le message de requête lorsque la stratégie est associée au flux de la requête et au message de réponse lorsque la stratégie est associée au flux de réponse.

Valeur par défaut	requête
Obligatoire ?	Facultatif
Type	Chaîne
Élément parent	<Source>
Éléments enfants	Aucun

Syntaxe

L'élément <Source> utilise la syntaxe suivante :

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

Exemple

L'exemple suivant évalue automatiquement le message de requête lorsque la règle est associée au flux de la requête et le message de réponse lorsque la règle est associée au flux de réponse :

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

L'élément <Source> ne comporte aucun attribut ni élément enfant.

Schéma de cette règle

Chaque type de règle est défini par un schéma XML (.xsd). Pour référence, des schémas de règles sont disponibles sur GitHub.

Codes d'erreur

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés et les variables d'erreur définies par Apigee lorsque cette règle déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Code d'erreur	État HTTP	Cause
steps.oasvalidation.Failed	400	Le corps du message de la requête ne peut pas être validé par rapport à la spécification OpenAPI fournie.
steps.oasvalidation.Failed	500	Le corps du message de réponse ne peut pas être validé par rapport à la spécification OpenAPI fournie.
steps.oasvalidation.SourceMessageNotAvailable	500	La variable spécifiée dans l'élément <Source> de la règle ne relève pas du champ d'application ou ne peut pas être résolue.
steps.oasvalidation.NonMessageVariable	500	L'élément <Source> est défini sur une variable qui n'est pas de type message.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Nom de l'erreur	Cause
ResourceDoesNotExist	La spécification OpenAPI référencée dans l'élément <OASResource> n'existe pas.
ResourceCompileFailed	La spécification OpenAPI incluse dans le déploiement contient des erreurs qui empêchent sa compilation. Cela indique généralement que la spécification n'est pas une spécification OpenAPI 3.0 correctement formulée.
BadResourceURL	La spécification OpenAPI référencée dans l'élément <OASResource> ne peut pas être traitée. Cela peut se produire si le fichier n'est pas un fichier JSON ou YAML, ou si l'URL du fichier n'est pas spécifiée correctement.

Variables de panne

Ces variables sont définies lorsque cette règle déclenche une erreur au moment de l'exécution. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Variable	Description	Exemple
fault.category	Catégorie de l'erreur. Lorsque la règle refuse une requête, cette variable conserve toujours la valeur Step.	fault.category = "Step"
fault.name	Nom de l'erreur, tel qu'indiqué dans le tableau Erreurs d'exécution ci-dessus. Le nom d'erreur est la dernière partie du code d'erreur.	fault.name Matches "ResourceDoesNotExist"
fault.reason	Cause de l'erreur. Il s'agit d'une chaîne lisible expliquant la raison de l'erreur.	OASValidation OAS-1 with resource "oas://my-spec1.yaml": failed with reason: "[ERROR - POST operation not allowed on path '/persons/13'.: []]"
fault.subcategory	Sous-catégorie de l'erreur. Lorsque la règle refuse une requête, cette variable conserve toujours la valeur OASValidationFailure.	fault.subcategory = "OASValidationFailure"
OASValidation.policy_name.failed	policy_name est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur.	OASValidation.myoaspolicy.failed = true

Fonctionnalités des spécifications OpenAPI compatibles

La règle OASValidation accepte les fonctionnalités de spécification OpenAPI récapitulées dans le tableau suivant, par catégorie. Les fonctionnalités non compatibles sont également répertoriées.

Remarque : La règle OASValidation rejette les spécifications OpenAPI qui utilisent des fonctionnalités non compatibles. Dans ce cas, la règle ne réussit pas la validation des fonctionnalités non compatibles et le déploiement du proxy d'API échoue.

Catégorie	Compatible	Incompatible
Formats de types de données	boolean date date-time double email float int32/int64 ipv4/ipv6 md5 sha1/sha256/sha512 string uri uri-template uuid	binary byte password
Objet discriminateur	mapping propertyName	ND
Objet de type de contenu	schema	encoding example examples
Objet opérations	parameters requestBody responses security (partial support)	callbacks deprecated servers
Objet paramètres	allowEmptyValue dans (query, header, path) required responses schema style (deepObject, form, formmatrix, label, pipeDelimited, simple, spaceDelimited) Remarque : deepObject ne prend en charge que les paramètres de chaîne ; les tableaux et les objets imbriqués ne sont pas compatibles.	allowReserved deprecated example examples content
Objet chemins	delete get head options parameters patch post put trace variables	servers
Objet corps de la requête	application/json application/hal+json application/x-www-form-urlencoded (objet encoding non compatible) content required	application/xml multipart/form-data text/plain text/xml
Objet réponse	application/json application/hal+json application/x-www-form-urlencoded (objet encoding non compatible) content headers	application/xml links text/plain text/xml
Objet réponses	default Code d'état HTTP	N/A
Objet schéma	$ref additionalProperties (variante d'option booléenne uniquement) allOf (ignored if additionalProperties is 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
Objet schéma de sécurité	dans (header, query) (ignoré si type est http) name type (apiKey, http)	bearerFormat flows openIdConnectUrl scheme
Objet serveur	url variables	Définition de plusieurs serveurs

Utiliser des modèles dans le schéma

La norme de spécification OpenAPI permet aux spécifications de stipuler un schema pour décrire le type de données d'un paramètre ou d'un champ. Pour un paramètre ou un champ de type chaîne, le schéma peut également définir un pattern, qui est une expression régulière qui définit les formes valides de la chaîne.

Prenons l'exemple du fragment de spécification OpenAPI suivant :

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}$'

Cette spécification exige que, pour l'opération getProduct, le paramètre product-id soit conforme à l'expression régulière donnée, qui stipule une séquence de trois caractères de mot, un tiret et quatre chiffres décimaux.

La spécification OpenAPI renvoie à la norme de validation de schéma JSON pour définir officiellement le comportement du modèle lors de la validation de la valeur de chaîne, et à la norme JSON Schema Core pour les recommandations aux auteurs de schémas concernant l'ensemble restreint de syntaxe d'expression régulière. Cette dernière norme recommande d'éviter l'utilisation de lookarounds (lookaheads et lookbehinds), de rétroréférences et d'expressions de caractères du système octal, entre autres, dans les modèles des documents de spécification OpenAPI.

Par défaut, Apigee valide le document de spécification OpenAPI référencé par la règle OASValidation et signale les erreurs si le document de spécification n'est pas bien formé. Apigee valide également les modèles d'expressions régulières dans votre document de spécification et signale les problèmes détectés.

Notez que si vous utilisez des fonctionnalités d'expressions régulières en dehors du sous-ensemble recommandé, Apigee ne valide pas l'expression régulière et suspend toute validation supplémentaire de votre document de spécification OpenAPI. S'il existe une erreur dans le document ou dans l'expression régulière qui utilise une fonctionnalité en dehors du sous-ensemble recommandé, ou si la fonctionnalité d'expression régulière n'est pas compatible avec l'environnement d'exécution Apigee, l'erreur ne sera détectée qu'au moment de l'exécution de la règle.

Le tableau suivant fournit quelques exemples.

Modèle	Comportement
^\w{3}-\d{4}$	Le modèle est valide. Il n'utilise que les fonctionnalités d'expressions régulières du sous-ensemble recommandé. Apigee permet d'enregistrer ou d'importer le proxy. Lors de l'exécution, la règle OASValidation fonctionne comme prévu, en validant le paramètre par rapport au modèle.
^([a-z]\w{3}-\d{4}$	Le modèle n'est pas valide, car il manque une parenthèse fermante. Le modèle n'utilise pas de fonctionnalités d'expressions régulières en dehors du sous-ensemble recommandé. Apigee signalera cette erreur lorsque vous importerez ou enregistrerez votre proxy d'API.
^(?![a-z]\w{3}-\d{4}$	Le modèle n'est pas valide. Comme dans l'exemple précédent, il manque une parenthèse fermante. Toutefois, Apigee ne signalera pas cette erreur au moment où vous enregistrerez ou importerez votre proxy d'API, car l'expression régulière utilise une recherche lookahead négative, qui n'est pas incluse dans le sous-ensemble recommandé de fonctionnalités d'expression régulière. L'erreur ne sera détectée qu'au moment de l'exécution de la règle.
^(?![a-z])\w{3}-\d{4}$	Le modèle est valide, mais il utilise une recherche lookahead négative, qui n'est pas recommandée. Apigee suspend la validation du document de spécification OpenAPI. Au moment de l'exécution, lorsque vous exécutez la règle OASValidation qui fait référence à une spécification à l'aide de ce modèle, Apigee applique correctement cette expression régulière pour valider la valeur du paramètre, car l'environnement d'exécution Apigee accepte les recherches anticipées négatives.
^(a)?b(?(1)c|d)$	Le modèle est valide, mais il utilise une condition de groupe de capture, qui se trouve en dehors du sous-ensemble recommandé de fonctionnalités d'expressions régulières. Apigee suspend la validation du document de spécification OpenAPI. Au moment de l'exécution, lorsque vous exécutez la règle OASValidation qui fait référence à une spécification à l'aide de ce modèle, Apigee renvoie une erreur, car l'environnement d'exécution Apigee n'est pas compatible avec cette fonctionnalité d'expression régulière.

Nous vous recommandons de n'utiliser que le sous-ensemble de fonctionnalités recommandé dans votre expression régulière pour éviter les échecs d'exécution.

Articles associés

• Règle de protection contre les menaces JSON
• Règle SOAPMessageValidation