Modular RAML mit Include, Bibliotheken, Overlays und Erweiterungen

1. Einführung

In unserem Link:/raml-restful-api-modeling-language-tutorial[erster] zwei Artikel zu RAML - der RESTful API Modeling Language - haben wir vorgestellt einige grundlegende Syntax, einschließlich der Verwendung von Datentypen und des JSON-Schemas, und wir haben gezeigt, wie Sie eine RAML-Definition vereinfachen, indem Sie allgemeine Muster in resource types und traits extrahieren.

In diesem Artikel zeigen wir, wie Sie Ihre RAML-API-Definition in Module aufteilen können, indem Sie includes , libraries , overlays und extensions verwenden.

2. Unsere API

In diesem Artikel konzentrieren wir uns auf den Teil unserer API, der den Entitätstyp Foo enthält.

Hier sind die Ressourcen, aus denen sich unsere API zusammensetzt:

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

3. Beinhaltet

Der Zweck eines include besteht darin, einen komplexen Eigenschaftswert in einer RAML-Definition zu modulieren, indem der Eigenschaftswert in einer externen Datei platziert wird.

In unserem ersten Artikel wurde kurz auf die Verwendung von includes eingegangen, als Datentypen und Beispiele angegeben wurden, deren Eigenschaften in der gesamten API inline wiederholt wurden.

3.1. Allgemeine Verwendung und Syntax

Das Tag ! Include hat ein einziges Argument: den Speicherort der externen Datei, die den Eigenschaftswert enthält. Dieser Speicherort kann eine absolute URL, ein Pfad relativ zur Stamm-RAML-Datei oder ein Pfad relativ zur einschließenden Datei sein.

Ein Ort, der mit einem Schrägstrich (/) beginnt, gibt einen Pfad relativ zum Speicherort der Root-RAML-Datei an, und ein Speicherort, der ohne Schrägstrich beginnt, wird als relativ zum Speicherort der enthaltenen Datei interpretiert.

Die logische Folge des letzteren ist, dass eine eingeschlossene Datei selbst andere ! Include -Direktiven enthalten kann.

Hier ist ein Beispiel, das alle drei Verwendungen des ! Include -Tags zeigt:

#%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. Typisierte Fragmente

Anstatt alle types , resource types oder traits in ihre eigenen include -Dateien zu platzieren, können Sie auch spezielle includes -Typen, die als typed fragmente bezeichnet werden, verwenden, um jedes dieser Konstrukte in mehrere include -Dateien aufzuteilen, wobei für jeden type , resource eine andere Datei angegeben wird type oder trait .

Sie können typed fragmente auch verwenden, um user-Dokumentationselemente , name beispiele , annotations , libraries , overlays und extensions zu definieren. Wir werden die Verwendung von overlays und extensions__ später im Artikel behandeln.

Obwohl es nicht erforderlich ist, kann die erste Zeile einer include -Datei, die ein typiertes Fragment ist, ein RAML-Fragmentbezeichner des folgenden Formats sein:

#%RAML 1.0 <fragment-type>

Die erste Zeile einer typen Fragmentdatei für ein trait__ wäre beispielsweise:

#%RAML 1.0 Trait

Wenn ein Fragmentbezeichner verwendet wird, MUSS der Inhalt der Datei nur gültige RAMLs für den angegebenen Fragmenttyp enthalten.

Schauen wir uns zunächst einen Teil des Abschnitts traits unserer API an:

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

Um diesen Abschnitt mit typed Fragments zu modularisieren, schreiben wir zuerst den Abschnitt traits wie folgt:

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

Wir würden dann die typed fragment -Datei hasRequestItem.raml schreiben:

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

Die typed Fragmentdatei hasResponseItem.raml__ würde folgendermaßen aussehen:

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

4. Bibliotheken

RAML libraries kann verwendet werden, um eine beliebige Anzahl und Kombination von datentypen , Sicherheitsschemata , resourcentypen , traits und annotations zu modulieren.

4.1. Definieren einer Bibliothek

Obwohl normalerweise in einer externen Datei definiert, die dann als include referenziert wird, kann eine library auch inline definiert werden. Eine in einer externen Datei enthaltene library kann auch auf andere libraries verweisen.

Im Gegensatz zu einem normalen include - oder typed-Fragment muss eine in einer externen Datei enthaltene library die Elementnamen der obersten Ebene angeben, die definiert werden.

Schreiben wir unseren traits -Abschnitt als library -Datei neu:

#%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. Anwenden einer Bibliothek

Libraries werden über die uses -Eigenschaft der obersten Ebene angewendet, deren Wert ein oder mehrere Objekte ist, deren Eigenschaftsnamen die library -Namen sind und deren Eigenschaftswerte den Inhalt der libraries ausmachen.

Nachdem wir die libraries für unsere security-Schemas , data types , resource types und traits erstellt haben, können wir die libraries auf die Stamm-RAML-Datei anwenden:

#%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. Verweis auf eine Bibliothek

Auf eine Library wird verwiesen, indem der Library -Name, ein Punkt (.) Und der Name des Elements (z. B. Datentyp, Ressourcentyp, Eigenschaft usw.), auf das verwiesen wird, verkettet wird.

Sie können sich über unser vorheriger Artikel daran erinnern, wie wir unsere resource types mithilfe der von uns definierten traits umgestaltet haben. Das folgende Beispiel zeigt, wie Sie den resource type von "item" als library umschreiben, wie Sie die traits library -Datei (siehe oben) in die neue library aufnehmen, und wie Sie auf traits verweisen, indem Sie die trait -Namen mit ihrem library -Namenqualifikator voranstellen (" 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. Overlays und Erweiterungen

Overlays und extensions sind Module, die in externen Dateien definiert sind und zum Erweitern einer API verwendet werden. An overlay wird verwendet, um nicht verhaltensrelevante Aspekte einer API zu erweitern, z. B. Beschreibungen, Verwendungshinweise und Benutzerdokumentationselemente, während eine Erweiterung verwendet wird, um Verhaltensaspekte der API zu erweitern oder zu überschreiben.

Im Gegensatz zu includes , auf die von anderen RAML-Dateien verwiesen wird, als ob sie inline codiert würden, müssen alle overlay - und extension -Dateien einen Verweis (über die masterRef -Eigenschaft der obersten Ebene) auf ihre Master-Datei enthalten, die entweder gültig ist RAML-API-Definition oder eine andere overlay - oder extension -Datei, auf die sie angewendet werden sollen.

5.1. Definition

Die erste Zeile einer Overlay- oder Erweiterungsdatei muss wie folgt formatiert werden:

RAML 1.0 Overlay

Und die erste Zeile einer Overlay-Datei muss ähnlich formatiert werden:

RAML 1.0 Extension

5.2. Nutzungsbeschränkungen

Bei Verwendung eines Satzes von overlays und/oder extensions müssen sich alle auf dieselbe Master-RAML-Datei beziehen. Außerdem erwarten RAML-Verarbeitungstools normalerweise, dass die Stamm-RAML-Datei und alle overlay - und extension -Dateien eine gemeinsame Dateierweiterung haben (z. B. „.raml“).

5.3. Anwendungsfälle für Überlagerungen

Die Motivation hinter overlays ist es, einen Mechanismus bereitzustellen, um die Schnittstelle von der Implementierung zu trennen. Dadurch können sich die eher humanorientierten Teile einer RAML-Definition ändern oder häufiger werden, während die Kernverhaltensaspekte der API stabil bleiben.

Ein üblicher Anwendungsfall für overlays ist die Bereitstellung von Benutzerdokumentation und anderen beschreibenden Elementen in mehreren Sprachen. Schreiben wir den Titel unserer API neu und fügen Sie einige Elemente der Benutzerdokumentation hinzu:

#%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.

So definieren wir eine spanische Sprachüberlagerung für diesen Abschnitt:

#%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.

Ein weiterer häufiger Anwendungsfall für overlays ist das Externalisieren von annotation -Metadaten, die im Wesentlichen eine Möglichkeit sind, einer API nicht standardisierte Konstrukte hinzuzufügen, um Hooks für RAML-Prozessoren wie Test- und Überwachungstools bereitzustellen.

5.4. Anwendungsfälle für Erweiterungen

Wie Sie dem Namen entnehmen können, werden mit extensions eine API erweitert, indem Sie neue Verhalten hinzufügen und/oder vorhandene Verhalten einer API ändern.

Eine Analogie aus der objektorientierten Programmierwelt wäre eine Unterklasse, die eine Superklasse erweitert, wobei die Unterklasse neue Methoden hinzufügen und/oder vorhandene Methoden überschreiben kann. Eine Erweiterung kann auch die nicht funktionalen Aspekte einer API erweitern.

Eine Erweiterung kann zum Beispiel verwendet werden, um zusätzliche Ressourcen zu definieren, die nur ausgewählten Benutzern zugänglich sind, z. Eine extension kann auch verwendet werden, um Features für eine neuere Version einer API hinzuzufügen.

Nachfolgend finden Sie eine Erweiterung, die die Version unserer API überschreibt und Ressourcen hinzufügt, die in der vorherigen Version nicht verfügbar waren:

#%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]----

Und hier ist ein spanisches __overlay__ für diese __Erweiterung__:

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

Es sei hier darauf hingewiesen, dass wir zwar in diesem Beispiel ein __overlay__ für die spanischsprachigen Überschreibungen verwendet haben, weil dadurch keine Verhaltensweisen der API geändert werden, wir hätten dieses Modul jedoch genauso leicht als __extension__ definieren können. Und es kann geeigneter als eine Erweiterung definiert werden, da es Zweck ist, Eigenschaften zu überschreiben, die in der englischsprachigen Erweiterung darüber zu finden sind.

===  **  6. Fazit**

In diesem Lernprogramm haben wir verschiedene Techniken eingeführt, um eine RAML-API-Definition modularer zu gestalten, indem gängige Konstrukte in externe Dateien aufgeteilt werden.

Zuerst haben wir gezeigt, wie das __include__-Feature in RAML verwendet werden kann, um einzelne, komplexe Eigenschaftswerte in wiederverwendbare externe Dateimodule umzuwandeln, die als __typed fragmente__ bezeichnet werden. Als Nächstes haben wir einen Weg demonstriert, mit dem __include__-Feature bestimmte Elementgruppen in wiederverwendbare __libraries__ zu externalisieren. Schließlich haben wir einige Verhaltens- und Nicht-Verhaltensaspekte einer API durch die Verwendung von __overlays__ und __extensions__ erweitert.

Um mehr über RAML-Modularisierungstechniken zu erfahren, besuchen Sie bitte die https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#modularization .

Sie können die **  vollständige Implementierung **  der für dieses Lernprogramm verwendeten API-Definition unter https://github.com/eugenp/tutorials/tree/master/raml/modularization (im github-Projekt) anzeigen.

Nächster ** "**

https://www.baeldung.com/raml-custom-properties-with-annotations[Anpassen benutzerdefinierter RAML-Eigenschaften mithilfe von Anmerkungen]

** "**  Bisherige

https://www.baeldung.com/simple-raml-mit-resource-typesundtraits
Redundanzen in RAML mit Ressourcentypen und Merkmalen]

TOC