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

1. Introduction

Dans notre lien:/raml-restful-api-modeling-language-tutorial[premier] deux articles sur RAML - le langage de modélisation d’API RESTful - que nous avons présenté Certaines syntaxes de base, notamment l’utilisation de types de données et de schémas JSON, nous ont montré comment simplifier une définition RAML en extrayant des modèles courants dans resource types et traits .

Dans cet article, nous montrons comment diviser la définition de votre API RAML en modules en utilisant includes , libraries , overlays et extensions .

2. Notre API

Pour les besoins de cet article, nous allons nous concentrer sur la partie de notre API impliquant le type d’entité appelé Foo .

Voici les ressources constituant notre API:

GET /api/v1/foos
POST /api/v1/foos
GET /api/v1/foos/\ {fooId}
PUT /api/v1/foos/\ {fooId}
DELETE /api/v1/foos/\ {fooId}

3. Comprend

Le but d’un include est de modulariser une valeur de propriété complexe dans une définition RAML en plaçant la valeur de la propriété dans un fichier externe.

Notre premier article traite brièvement de l’utilisation de includes lorsque nous spécifions des types de données et des exemples dont les propriétés étaient répétées en ligne dans toute l’API.

3.1. Utilisation générale et syntaxe

La balise ! Include prend un seul argument: l’emplacement du fichier externe contenant la valeur de la propriété. Cet emplacement peut être une URL absolue, un chemin relatif au fichier RAML racine ou un chemin relatif au fichier inclus.

Un emplacement commençant par une barre oblique (/) indique un chemin relatif à l’emplacement du fichier RAML racine et un emplacement commençant sans barre oblique est interprété comme étant relatif à l’emplacement du fichier inclus.

Le corollaire logique de ce dernier est qu’un fichier inclus peut contenir lui-même d’autres directives ! Include .

Voici un exemple montrant les trois utilisations de la balise ! Include :

#%RAML 1.0
title: Baeldung Foo REST Services API
...
types: !include/types/allDataTypes.raml
resourceTypes: !include allResourceTypes.raml
traits: !include http://foo.com/docs/allTraits.raml

3.2. Fragments dactylographiés

Plutôt que de placer tous les types , resource types ou traits dans leurs propres fichiers include respectifs, vous pouvez également utiliser des types spéciaux de includes appelés typed fragments pour décomposer chacune de ces constructions en plusieurs fichiers include , en spécifiant un fichier différent pour chaque type , resource type ou trait .

Vous pouvez également utiliser typed fragments pour définir les éléments de documentation de user, nommés exemples , annotations , libraries , overlays et extensions . Nous aborderons l’utilisation de overlays et extensions__ plus tard dans l’article.

Bien que cela ne soit pas obligatoire, la première ligne d’un fichier include qui est un fragment typed peut être un identificateur de fragment RAML du format suivant:

#%RAML 1.0 <fragment-type>

Par exemple, la première ligne d’un fichier typed fragment pour un trait serait:

#%RAML 1.0 Trait

Si un identificateur de fragment est utilisé, le contenu du fichier DOIT contenir uniquement la RAML valide pour le type de fragment spécifié.

Examinons d’abord une partie de la section traits de notre API:

traits:
  - hasRequestItem:
      body:
        application/json:
          type: <<typeName>>
  - hasResponseItem:
      responses:
          200:
            body:
              application/json:
                type: <<typeName>>
                example: !include examples/<<typeName>>.json

Afin de modulariser cette section à l’aide de typed fragments , nous réécrivons tout d’abord la section traits comme suit:

traits:
  - hasRequestItem: !include traits/hasRequestItem.raml
  - hasResponseItem: !include traits/hasResponseItem.raml

Nous écririons ensuite le fichier typed fragment hasRequestItem.raml :

#%RAML 1.0 Trait
body:
  application/json:
    type: <<typeName>>

Le fichier fragment typed hasResponseItem.raml__ ressemblerait à ceci:

#%RAML 1.0 Trait
responses:
    200:
      body:
        application/json:
          type: <<typeName>>
          example: !include/examples/<<typeName>>.json

4. Bibliothèques

RAML libraries peut être utilisé pour modulariser tout nombre et toute combinaison de data types , security scheme , resource types , traits et annotations .

4.1. Définir une bibliothèque

Bien que généralement défini dans un fichier externe, qui est ensuite référencé en tant que include , une library peut également être définie en ligne. Une bibliothèque contenue dans un fichier externe peut également faire référence à d’autres bibliothèques.

Contrairement à un fragment include ou __typed normal, une bibliothèque contenue dans un fichier externe doit déclarer les noms d’éléments de niveau supérieur en cours de définition.

Réécrivons notre section traits sous la forme d’un fichier library :

#%RAML 1.0 Library
# This is the file/libraries/traits.raml
usage: This library defines some basic traits
traits:
  hasRequestItem:
    usage: Use this trait for resources whose request body is a single item
    body:
      application/json:
        type: <<typeName>>
  hasResponseItem:
    usage: Use this trait for resources whose response body is a single item
    responses:
        200:
          body:
            application/json:
              type: <<typeName>>
              example: !include/examples/<<typeName>>.json

4.2. Appliquer une bibliothèque

Les bibliothèques sont appliquées via la propriété uses de niveau supérieur, dont la valeur correspond à un ou plusieurs objets dont les noms de propriété sont les noms library et dont les valeurs de propriété constituent le contenu de libraries .

Une fois que nous avons créé les bibliothèques pour nos schémas de sécurité, types de données, types de ressources et types de données, nous pouvons appliquer les bibliothèques au fichier RAML racine:

#%RAML 1.0
title: Baeldung Foo REST Services API
uses:
  mySecuritySchemes: !include libraries/security.raml
  myDataTypes: !include libraries/dataTypes.raml
  myResourceTypes: !include libraries/resourceTypes.raml
  myTraits: !include libraries/traits.raml

4.3. Référencer une bibliothèque

Une bibliothèque est référencée en concaténant le nom de la bibliothèque, un point (.) Et le nom de l’élément (type de données, type de ressource, trait, etc.).

Vous pouvez vous rappeler de notre article précédent comment nous avons restructuré notre resource sources avec le traits que nous avions défini. L’exemple suivant montre comment réécrire notre «élément» resource type en tant que library, comment inclure le fichier trait library (illustré ci-dessus) dans la nouvelle library et comment référencer trait en préfixant les noms trait avec leur qualificateur library (“ MyTraits “):

#%RAML 1.0 Library
# This is the file/libraries/resourceTypes.raml
usage: This library defines the resource types for the API
uses:
  myTraits: !include traits.raml
resourceTypes:
  item:
    usage: Use this resourceType to represent any single item
    description: A single <<typeName>>
    get:
      description: Get a <<typeName>> by <<resourcePathName>>
      is:[myTraits.hasResponseItem, myTraits.hasNotFound]    put:
      description: Update a <<typeName>> by <<resourcePathName>>
      is:[myTraits.hasRequestItem, myTraits.hasResponseItem, myTraits.hasNotFound]    delete:
      description: Delete a <<typeName>> by <<resourcePathName>>
      is:[myTraits.hasNotFound]      responses:
        204:

5. Superpositions et extensions

Overlays et extensions sont des modules définis dans des fichiers externes utilisés pour étendre une API. Une superposition est utilisée pour étendre les aspects non comportementaux d’une API, tels que les descriptions, les instructions d’utilisation et les éléments de documentation utilisateur, tandis qu’une extension est utilisée pour étendre ou remplacer les aspects comportementaux de l’API.

Contrairement à includes , qui sont référencés par d’autres fichiers RAML à appliquer comme s’ils étaient codés en ligne, tous les fichiers overlay et extension doivent contenir une référence (via la propriété masterRef de niveau supérieur) à son fichier maître, qui peut être un Définition de l’API RAML ou d’un autre fichier overlay ou extension auquel ils doivent être appliqués.

5.1. Définition

La première ligne d’un fichier de superposition ou d’un fichier d’extension doit être formatée comme suit:

RAML 1.0 Overlay

Et la première ligne d’un fichier de surimpression doit être formatée de la même manière:

RAML 1.0 Extension

5.2. Contraintes d’utilisation

Lorsque vous utilisez un ensemble de overlays et/ou extensions , ils doivent tous se référer au même fichier RAML maître. En outre, les outils de traitement RAML s’attendent généralement à ce que le fichier RAML racine et tous les fichiers overlay et extension aient une extension de fichier commune (par exemple, «.raml»).

5.3. Cas d’utilisation pour superpositions

Le but de overlays est de fournir un mécanisme permettant de séparer l’interface de l’implémentation, permettant ainsi aux parties plus orientées humaines d’une définition RAML de changer ou de se développer plus fréquemment, tandis que les aspects comportementaux de l’API restent stables.

Un cas d’utilisation courant pour overlays est de fournir une documentation utilisateur et d’autres éléments descriptifs dans plusieurs langues. Réécrivons le titre de notre API et ajoutons quelques éléments de documentation utilisateur:

#%RAML 1.0
title: API for REST Services used in the RAML tutorials on Baeldung.com
documentation:
  - title: Overview
  - content: |
      This document defines the interface for the REST services
      used in the popular RAML Tutorial series at Baeldung.com.
  - title: Copyright
  - content: Copyright 2016 by Baeldung.com. All rights reserved.

Voici comment nous définirions une superposition de langue espagnole pour cette section:

#%RAML 1.0 Overlay
# File located at (archivo situado en):
#/overlays/es__ES/documentationItems.raml
masterRef:/api.raml
usage: |
  To provide user documentation and other descriptive text in Spanish
  (Para proporcionar la documentación del usuario y otro texto descriptivo
  en español)
title: |
  API para servicios REST utilizados en los tutoriales RAML
  en Baeldung.com
documentation:
  - title: Descripción general
  - content: |
      Este documento define la interfaz para los servicios REST
      utilizados en la popular serie de RAML Tutorial en Baeldung.com.
  - title: Derechos de autor
  - content: |
      Derechos de autor 2016 por Baeldung.com.
      Todos los derechos reservados.

Un autre cas d’utilisation courant de overlays consiste à externaliser les métadonnées annotation , qui constituent essentiellement un moyen d’ajouter des constructions non standard à une API afin de fournir des points d’ancrage aux processeurs RAML tels que les outils de test et de surveillance.

5.4. Cas d’utilisation pour les extensions

Comme vous pouvez en déduire le nom, les extensions sont utilisées pour étendre une API en ajoutant de nouveaux comportements et/ou en modifiant les comportements existants d’une API.

Une analogie du monde de la programmation orientée objet serait une sous-classe étendant une super-classe, où la sous-classe peut ajouter de nouvelles méthodes et/ou remplacer des méthodes existantes. Une extension peut également étendre les aspects non fonctionnels d’une API.

Une extension peut être utilisée, par exemple, pour définir des ressources supplémentaires exposées uniquement à un ensemble d’utilisateurs sélectionné, telles que des administrateurs ou des utilisateurs auxquels un rôle particulier a été attribué. Un extension peut également être utilisé pour ajouter des fonctionnalités à une version plus récente d’une API.

Ci-dessous, une extension qui remplace la version de notre API et ajoute des ressources non disponibles dans la version précédente:

#%RAML 1.0 Extension
# File located at:
#/extensions/en__US/additionalResources.raml
masterRef:/api.raml
usage: This extension defines additional resources for version 2 of the API.
version: v2/foos:
 /bar/{barId}:
    get:
      description: |
        Get the foo that is related to the bar having barId = {barId}
      typeName: Foo
      queryParameters:
        barId?: integer
        typeName: Foo
        is:[hasResponseItem]----

Et voici un __overlay__ en espagnol pour cette __extension__:

[source,javascript,gutter:,true]

#%RAML 1.0 Overlay # Archivo situado en: #/overlays/es__ES/additionalResources.raml masterRef:/api.raml usage: | Se trata de un español demasiado que describe los recursos adicionales para la versión 2 del API. version: v2/foos: /bar/{barId}: get: description: | Obtener el foo que se relaciona con el bar tomando barId = {barId}

Il convient de noter ici que bien que nous ayons utilisé un __overlay__ pour les substitutions en langue espagnole dans cet exemple car il ne modifie aucun comportement de l'API, nous aurions tout aussi bien pu définir ce module comme étant un __extension__. Et il peut être plus approprié de définir une extension, étant donné que son objectif est de remplacer les propriétés trouvées dans l'extension de langue anglaise au-dessus.

===  **  6. Conclusion**

Dans ce didacticiel, nous avons introduit plusieurs techniques pour rendre une définition d’API RAML plus modulaire en séparant les constructions communes en fichiers externes.

Tout d'abord, nous avons montré comment la fonctionnalité __include__ de RAML peut être utilisée pour reformuler des valeurs de propriétés individuelles et complexes dans des modules de fichiers externes réutilisables, appelés __typed fragments__. Ensuite, nous avons montré comment utiliser la fonctionnalité __include__ pour externaliser certains ensembles d’éléments dans des bibliothèques réutilisables. Enfin, nous avons étendu certains aspects comportementaux et non comportementaux d’une API en utilisant __overlays__ et __extensions__.

Pour en savoir plus sur les techniques de modularisation de RAML, veuillez consulter la page https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#modularization[RAML 1.0].

Vous pouvez voir la **  mise en œuvre complète **  de la définition d'API utilisée pour ce tutoriel dans https://github.com/eugenp/tutorials/tree/master/raml/modularization[le projet github].

Suivant ** "**

https://www.baeldung.com/raml-custom-properties-with-annotations[Define Custom RAML Properties utilisant Annotations]

** "**  Précédent

https://www.baeldung.com/simple-raml-with-resource-types-and-traits[Eliminate
Redondances dans RAML avec types de ressources et caractéristiques]

TOC