Définir les propriétés RAML personnalisées à l’aide d’annotations

1. Introduction

Dans ce quatrième article de notre série sur RAML - le langage de modélisation d’API RESTful -, nous montrons comment utiliser annotations pour définir des propriétés personnalisées pour une spécification d’API RAML. Ce processus est également appelé extension des métadonnées de la spécification.

Les annotations peuvent être utilisées pour fournir des points d’ancrage aux outils de traitement RAML nécessitant des spécifications supplémentaires qui ne relèvent pas de la langue officielle.

2. Déclaration de types d’annotation

Un ou plusieurs annotation types peuvent être déclarés à l’aide de la propriété annotationTypes de niveau supérieur.

Dans le plus simple des cas, le type annotation name est tout ce qui est nécessaire pour le spécifier.

annotationTypes:
  simpleImplicitStringValueType:

C’est l’équivalent de la définition plus explicite de annotation type présentée ici:

annotationTypes:
  simpleExplicitStringValueType:
    type: string

Dans d’autres cas, une spécification annotation type contiendra un objet valeur considéré comme étant le type annotation déclaration .

Dans ces cas, la annotation type est définie en utilisant la même syntaxe qu’un data type avec l’ajout de deux attributs facultatifs:

allowedTargets , dont la valeur est une chaîne ou un tableau de chaînes limitant les types d’emplacements cibles auxquels une annotation peut être appliquée, et allowMultiple , dont la valeur booléenne indique si la annotation peut être appliquée plusieurs fois dans une même cible ( la valeur par défaut est false__).

Voici un bref exemple déclarant une annotation type contenant des propriétés et des attributs supplémentaires:

annotationTypes:
  complexValueType:
    allowMultiple: true
    properties:
      prop1: integer
      prop2: string
      prop3: boolean

2.1. Emplacements cibles prenant en charge l’utilisation d’annotations

Annotations peut être appliqué à (utilisé dans) plusieurs emplacements cibles de niveau racine, y compris le niveau racine de l’API lui-même, types de sources , traits , types de données , éléments de documentation, systèmes de sécurité , libraries , overlays , overlays , extensions et autres types d’annotation .

Les annotations peuvent également être appliquées aux paramètres de schéma de sécurité, aux ressources, aux méthodes, aux déclarations, aux réponses, aux demandes, aux réponses et aux exemples nommés.

2.2. Limiter les cibles d’un type d’annotation

Pour limiter un typeannotation à un ou plusieurs types d’emplacement cible spécifiques, définissez son attribut allowedTargets__.

Lorsque vous limitez un annotation type à un seul type d’emplacement cible, vous affectez à l’attribut allowedTargets une valeur de chaîne représentant ce type d’emplacement cible:

annotationTypes:
  supportsOnlyOneTargetLocationType:
    allowedTargets: TypeDeclaration

Pour autoriser plusieurs types d’emplacement cible pour un type d’annotation, vous devez affecter à l’attribut allowedTargets un tableau de valeurs de chaîne représentant ces types d’emplacement cible:

annotationTypes:
  supportsMultipleTargetLocationTypes:
    allowedTargets:[Library, Overlay, Extension]----

Si l'attribut __allowedTargets__ n'est pas défini sur une __annotation type__, alors par défaut, cette __annotation type__ peut être appliquée à l'un des types d'emplacement cible pris en charge.

[[applying]]

===  **  3. Application de types d'annotation **

Une fois que vous avez défini les types d'annotation au niveau racine de votre spécification d'API RAML, vous devez les appliquer aux emplacements cibles souhaités, en fournissant leurs valeurs de propriété à chaque instance. L'application d'un __annotation type__ dans un emplacement cible est simplement appelée un __annotation__ sur cet emplacement cible.

====  **  3.1. Syntaxe**

Pour appliquer un __annotation type__, ajoutez le type __annotation name__ entre parenthèses () en tant qu'attribut de l'emplacement cible et indiquez les propriétés __annotation type value__ que le __annotation type__ doit utiliser pour cette cible spécifique. Si __annotation type__ se trouve dans une bibliothèque RAML __, vous devez alors concaténer la référence __library__ suivie d'un point (.) Suivi du nom du type __annotation.__

====  **  3.2. Exemple**

Voici un exemple montrant comment nous pourrions appliquer certaines des __annotation types__ répertoriées dans les extraits de code ci-dessus à diverses __resources__ et __methods__ de notre API:

[source,javascript,gutter:,true]

----/foos:
  type: myResourceTypes.collection
  (simpleImplicitStringValueType): alpha
  ...
  get:
    (simpleExplicitStringValueType): beta
  ...
 /{fooId}:
    type: myResourceTypes.item
    (complexValueType):
      prop1: 4
      prop2: testing
      prop3: true

4. Cas d’utilisation

Un cas d’utilisation potentiel pour annotations serait de définir et de configurer des cas de test pour une API.

Supposons que nous voulions développer un outil de traitement RAML pouvant générer une série de tests sur notre API basée sur annotations . Nous pourrions définir le type d’annotation suivant:

annotationTypes:
  testCase:
    allowedTargets:[Method]    allowMultiple: true
    usage: |
      Use this annotation to declare a test case.
      You may apply this annotation multiple times per location.
    properties:
      scenario: string
      setupScript?: string[]      testScript: string[]      expectedOutput?: string
      cleanupScript?: string[]----

Nous pourrions ensuite configurer une série de cas de test pour notre ressource __/foos__ en appliquant les annotations__ comme suit:

[source,javascript,gutter:,true]

----/foos:
  type: myResourceTypes.collection
  get:
    (testCase):
      scenario: No Foos
      setupScript: deleteAllFoosIfAny
      testScript: getAllFoos
      expectedOutput: ""
    (testCase):
      scenario: One Foo
      setupScript:[deleteAllFoosIfAny, addInputFoos]      testScript: getAllFoos
      expectedOutput: '[{ "id": 999, "name": Joe }]'
      cleanupScript: deleteInputFoos
    (testCase):
      scenario: Multiple Foos
      setupScript:[deleteAllFoosIfAny, addInputFoos]      testScript: getAllFoos
      expectedOutput: '[{ "id": 998, "name": "Bob" }, { "id": 999, "name": "Joe" }]'
      cleanupScript: deleteInputFoos

5. Conclusion

Dans ce tutoriel, nous avons montré comment étendre les métadonnées d’une spécification d’API RAML en utilisant des propriétés personnalisées appelées annotations .

Tout d’abord, nous avons montré comment déclarer annotation types à l’aide de la propriété annotationTypes de niveau supérieur et énumérer les types d’emplacements cibles auxquels ils sont autorisés à être appliqués.

Ensuite, nous avons montré comment appliquer annotations dans notre API et noté comment limiter les types d’emplacements cibles auxquels un annotation donné peut être appliqué.

Enfin, nous avons introduit un cas d’utilisation potentiel en définissant annotation types qui pourraient éventuellement être pris en charge par un outil de génération de tests et en montrant comment appliquer ces annotations à une API.

Pour plus d’informations sur l’utilisation de annotations dans RAML, visitez le site RAML 1.0 spec .

Vous pouvez voir la mise en œuvre complète de la définition de l’API utilisée pour ce tutoriel dans le projet github .

"** Précédent

Modular RAML Utilisation d’inclusions, de bibliothèques, de superpositions et d’extensions

TOC