インクルード、ライブラリ、オーバーレイ、拡張機能を使用したモジュラーRAML

投稿日: 2019-10-18 2022-10-19
タグ: RAML, REST

1. 序章

RAML（RESTful APIモデリング言語）に関する first two の記事では、データ型やJSONスキーマの使用など、いくつかの基本的な構文を紹介し、RAMLを簡素化する方法を示しました。共通パターンをリソースタイプおよび特性に抽出することによる定義。

この記事では、 include 、 libraries 、 overlays 、を利用して、RAMLAPI定義をモジュールに分割する方法を示します。および拡張機能。

2. 私たちのAPI

この記事では、Fooと呼ばれるエンティティタイプを含むAPIの部分に焦点を当てます。

APIを構成するリソースは次のとおりです。

GET / api / v1 / foos
POST / api / v1 / foos
GET / api / v1 / foos / {fooId}
PUT / api / v1 / foos / {fooId}
削除/api / v1 / foos / {fooId}

3. 含まれています

include の目的は、プロパティ値を外部ファイルに配置することにより、RAML定義の複雑なプロパティ値をモジュール化することです。

最初の記事では、API全体でプロパティがインラインで繰り返されるデータ型と例を指定する際のincludeの使用について簡単に触れました。

3.1. 一般的な使用法と構文

！include タグは、プロパティ値を含む外部ファイルの場所という1つの引数を取ります。この場所は、絶対URL、ルートRAMLファイルからの相対パス、またはインクルードファイルからの相対パスの場合があります。

スラッシュ（/）で始まる場所は、ルートRAMLファイルの場所からの相対パスを示し、スラッシュなしで始まる場所は、インクルードファイルの場所からの相対パスであると解釈されます。

後者の論理的な帰結は、インクルードされたファイル自体が他の！includeディレクティブを含む可能性があるということです。

！includeタグの3つの使用法すべてを示す例を次に示します。

#%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. 型付きフラグメント

すべてのタイプ、リソースタイプ、または特性をそれぞれのインクルードファイルに配置するのではなく、特別なタイプの[ X169X] include は、タイプのフラグメントと呼ばれ、これらの各構成を複数の include ファイルに分割し、タイプ、ごとに異なるファイルを指定します。リソースタイプまたは特性。

型付きフラグメントを使用して、ユーザードキュメントアイテム、名前付き例、注釈、ライブラリ、[ X154X]オーバーレイ、および拡張機能。 オーバーレイおよび拡張機能の使用については、この記事の後半で説明します。

必須ではありませんが、タイプのフラグメントである include ファイルの最初の行は、次の形式のRAMLフラグメント識別子である可能性があります。

#%RAML 1.0 <fragment-type>

たとえば、traitの型付きフラグメントファイルの最初の行は次のようになります。

#%RAML 1.0 Trait

フラグメント識別子が使用される場合、ファイルの内容には、指定されているフラグメントのタイプに対して有効なRAMLのみが含まれている必要があります。

まず、APIのtraitsセクションの一部を見てみましょう。

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

タイプのフラグメントを使用してこのセクションをモジュール化するために、最初にtraitsセクションを次のように書き直します。

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

次に、型付きフラグメントファイルhasRequestItem.ramlを記述します。

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

型付きフラグメントファイルhasResponseItem.ramlは次のようになります。

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

4. ライブラリ

RAML ライブラリは、データ型、セキュリティスキーム、リソースタイプ、特性の任意の数と組み合わせをモジュール化するために使用できます。 X163X]、および注釈。

4.1. ライブラリの定義

通常は外部ファイルで定義され、 include として参照されますが、ライブラリをインラインで定義することもできます。外部ファイルに含まれるライブラリは、他のライブラリも参照できます。

通常のincludeまたはタイプのフラグメントとは異なり、外部ファイルに含まれる library は、定義されている最上位の要素名を宣言する必要があります。

traitsセクションを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. ライブラリの適用

ライブラリはトップレベルのusesプロパティを介して適用されます。その値は、プロパティ名がライブラリ名であり、プロパティ値がライブラリの内容をアップします。

セキュリティスキーム、データ型、リソース型、および特性のライブラリを作成したら、 ライブラリをルートRAMLファイルに適用できます。

#%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. ライブラリを参照する

ライブラリは、ライブラリの名前、ドット（。）、および要素の名前を連結することによって参照されます（例：参照されているデータ型、リソースタイプ、特性など）。

以前の記事から、定義した特性を使用してリソースタイプをリファクタリングした方法を思い出してください。次の例は、「アイテム」リソースタイプをライブラリとして書き換える方法、 traits library ファイルを含める方法を示しています（図を参照）。上記）新しいライブラリ内、およびトレイト名の前にライブラリ名前修飾子（「[ X330X] 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. オーバーレイと拡張

オーバーレイおよび拡張機能は、APIを拡張するために使用される外部ファイルで定義されたモジュールです。 オーバーレイは、説明、使用方法、ユーザードキュメント項目など、APIの非動作面を拡張するために使用されますが、拡張は、の動作面を拡張またはオーバーライドするために使用されます。 API。

インラインでコーディングされているかのように適用される他のRAMLファイルによって参照されるincludesとは異なり、すべてのoverlayおよびextensionファイルには参照が含まれている必要があります（経由マスターファイルへのトップレベルのmasterRefプロパティ）。これは、有効なRAML API定義、または別のoverlayまたはextensionファイルのいずれかです。適用されます。

5.1. 意味

オーバーレイまたは拡張子ファイルの最初の行は、次のようにフォーマットする必要があります。

RAML 1.0 Overlay

また、オーバーレイファイルの最初の行も同様にフォーマットする必要があります。

RAML 1.0 Extension

5.2. 使用上の制約

オーバーレイおよび/または拡張機能のセットを使用する場合、それらすべてが同じマスターRAMLファイルを参照する必要があります。さらに、RAML処理ツールは通常、ルートRAMLファイルとすべてのオーバーレイおよび拡張子ファイルに共通のファイル拡張子（例：「.raml」）。

5.3. オーバーレイのユースケース

オーバーレイの背後にある動機は、インターフェースを実装から分離するメカニズムを提供することです。これにより、APIのコア動作の側面を安定させながら、RAML定義のより人間指向の部分をより頻繁に変更または拡張できるようになります。。

オーバーレイの一般的な使用例は、ユーザードキュメントやその他の説明要素を複数の言語で提供することです。 APIのタイトルを書き直して、いくつかのユーザードキュメントアイテムを追加しましょう。

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

このセクションのスペイン語オーバーレイを定義する方法は次のとおりです。

#%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 documentación del usuario y otro texto descriptivo
  en español)
title: |
  API para servicios REST utilizados en los tutoriales RAML
  en Baeldung.com
documentation:
  - title: Descripció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.

オーバーレイのもう1つの一般的な使用例は、アノテーションメタデータを外部化することです。これは、基本的に、テストや監視ツール。

5.4. 拡張機能のユースケース

名前から推測できるように、 extends は、APIの新しい動作を追加したり、既存の動作を変更したりすることでAPIを拡張するために使用されます。オブジェクト指向プログラミングの世界からのアナロジーは、スーパークラスを拡張するサブクラスであり、サブクラスは新しいメソッドを追加したり、既存のメソッドをオーバーライドしたりできます。拡張機能は、APIの非機能的側面も拡張する場合があります。

拡張機能は、たとえば、管理者や特定の役割が割り当てられているユーザーなど、選択したユーザーのセットにのみ公開される追加のリソースを定義するために使用できます。 拡張機能を使用して、新しいバージョンのAPIの機能を追加することもできます。

以下は、APIのバージョンをオーバーライドし、以前のバージョンでは利用できなかったリソースを追加する拡張機能です。

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

そして、これがその拡張機能のスペイン語オーバーレイです。

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

ここで注目に値するのは、この例ではスペイン語のオーバーライドに overlay を使用したため、APIの動作は変更されないため、このモジュールを[ X228X]拡張機能。また、その上の英語のエクステンションにあるプロパティをオーバーライドすることが目的であるため、エクステンションとしてより適切に定義できます。

6. 結論

このチュートリアルでは、一般的な構造を外部ファイルに分離することにより、RAMLAPI定義をよりモジュール化するためのいくつかの手法を紹介しました。

最初に、RAMLの include 機能を使用して、個々の複雑なプロパティ値を型付きフラグメントと呼ばれる再利用可能な外部ファイルモジュールにリファクタリングする方法を示しました。次に、 include 機能を使用して、特定の要素セットを再利用可能なライブラリに外部化する方法を示しました。最後に、オーバーレイおよび拡張機能を使用して、APIの動作面と非動作面を拡張しました。

RAMLモジュール化手法の詳細については、RAML1.0仕様にアクセスしてください。

このチュートリアルで使用されるAPI定義の完全な実装は、githubプロジェクトで確認できます。

getdocs

13036