1前書き

リンクでは:/raml-restful-apiモデリング言語のチュートリアル[first]リンク:/simple-raml-with-resources-types-and-traits[2]の記事 – RAML – RESTful APIモデリング言語 – データ型とJSONスキーマの使用を含むいくつかの基本的な構文、そして一般的なパターンを

resource types



traits

に抽出することによってRAML定義を単純化する方法を示しました。

この記事では、

includes



libraries



overlays

、および

extensions

を利用して、RAML API定義をモジュールに分割する方法を** 示します。


2私たちのAPI

この記事の目的のために、私たちは

Foo

と呼ばれるエンティティタイプを含む私たちのAPIの部分に焦点を合わせます。

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含まれています


include

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

最初の記事では、API全体でインラインで繰り返されるプロパティを持つデータ型と例を指定するときの

includes

の使用について簡単に触れました。


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


!include

タグは単一の引数を取ります。プロパティ値を含む外部ファイルの場所です。この場所は、絶対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. 型付きフラグメント

それぞれの

include

ファイルに

types



resource types

、または

traits

をすべて配置するのではなく、それぞれの

type



resourceごとに異なるファイルを指定して、

typed fragments

と呼ばれる特殊な

includes

を複数の

include

ファイルに分割できますtype

または

trait


typed fragments

を使用して、

ユーザードキュメント項目



名前付き例



注釈



ライブラリ



overlays

、および

extensions

を定義することもできます。この記事の後半で、

overlays



extensions

の使用方法について説明します。

必須ではありませんが、

typed fragment

である

include

ファイルの最初の行は、次の形式のRAMLフラグメント識別子です。

#%RAML 1.0 <fragment-type>

たとえば、

trait



typed fragment

ファイルの最初の行は次のようになります。

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

このセクションを

typed fragments

を使ってモジュール化するために、まず

traits

セクションを次のように書き換えます。

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

それから

typed fragment

ファイル

hasRequestItem.raml

を書くでしょう:

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


typed fragment

ファイル

hasResponseItem.raml

は次のようになります。

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


4図書館

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


4.1. ライブラリの定義

通常

include

として参照される外部ファイルで定義されていますが、

library

はインラインで定義することもできます。外部ファイルに含まれている

library

は、他の

libraries

も参照できます。

通常の

include



typed fragment

とは異なり、外部ファイルに含まれる

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. 図書館の申し込み


Libraries

はトップレベルの

uses

プロパティを介して適用されます。その値は、プロパティ名が

library

namesで、プロパティ値が

libraries

の内容を構成する1つ以上のオブジェクトです。


セキュリティスキーム



データ型



リソース型

、および

traits

用に

libraries

を作成したら、

libraries

をルート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. ライブラリの参照


library

は、

library

name、ドット(。)、および参照されている要素の名前(データタイプ、リソースタイプ、特性など)を連結することによって参照されます。


前の記事

で定義した

traits

を使って

resource types

をリファクタリングした方法を思い出してください。次の例は、「item」

resource type



libraryとして書き換える方法、


traits


library

ファイル(上記の)を新しい

library

内に含める方法、および

trait

名の先頭に

library

name修飾子を付けて

traits

を参照する方法を示しています(“

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



extensions

は、APIを拡張するために使用される外部ファイルで定義されたモジュールです。

overlay

は、説明、使用方法、ユーザードキュメントの項目など、APIの動作以外の側面を拡張するために使用されますが、

extension

は、APIの動作上の側面を拡張または上書きするために使用されます。

インラインでコーディングされているかのように適用される他のRAMLファイルによって参照される

includes

とは異なり、すべての

overlay

および

extension

ファイルはマスターファイルへの参照を含む必要があります。 RAML API定義、またはそれらが適用される別の

overlay

または

extension

ファイル。


5.1. 定義

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

RAML 1.0 Overlay

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

RAML 1.0 Extension


5.2. 使用制限


overlays

または

extensions

、あるいはその両方のセットを使用するときは、それらすべてが同じマスターRAMLファイルを参照している必要があります。さらに、RAML処理ツールは通常、ルートRAMLファイルならびにすべての

overlay

および

extension

ファイルが共通のファイル拡張子(例えば「.raml」)を有すると予想する。


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


overlays

の背後にある動機は、実装からインターフェースを分離するためのメカニズムを提供することです。そのため、APIの中心的な動作の側面は安定したままで、より人間指向のRAML定義の部分をより頻繁に変更または拡大できます。


overlays

の一般的なユースケースは、ユーザードキュメントと他の記述要素を多言語で提供することです。 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.


overlays

のもう1つの一般的なユースケースは

annotation

メタデータを外部化することです。これは基本的にテストや監視ツールなどのRAMLプロセッサ用のフックを提供するためにAPIに非標準コンストラクトを追加する方法です。


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

名前からわかるように、

extensions

は新しい振る舞いを追加したり既存の振る舞いを変更することによってAPIを拡張するために使用されます。

オブジェクト指向プログラミングの世界からの類推は、サブクラスが新しいメソッドを追加したり既存のメソッドをオーバーライドしたりできるスーパークラスを拡張するサブクラスです。拡張機能は、APIの機能的でない面も拡張する可能性があります。

たとえば、

extension

を使用して、管理者や特定のロールが割り当てられているユーザーなど、選択した一連のユーザーにのみ公開される追加のリソースを定義できます。

extension

は、新しいバージョンのAPIの機能を追加するためにも使用できます。

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

extension

です。

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

そして、これがそのためのスペイン語の__overlay__です。

[source,javascript,gutter:,true]

#%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の動作は変更されていないため、このモジュールを__extension__に定義することも簡単にできます。その目的は、その上の英語の__extension__にあるプロパティを上書きすることであることを考えると、それは__extension__としてより適切に定義されるかもしれません。

===  **  6. 結論**

このチュートリアルでは、共通の構成要素を外部ファイルに分離することによってRAML API定義をよりモジュール化するためのいくつかの手法を紹介しました。

まず、RAMLの__include__機能を使用して、個々の複雑なプロパティ値を__typed fragments__として知られる再利用可能な外部ファイルモジュールにリファクタリングする方法を示しました。次に、__include__機能を使用して特定の要素セットを再利用可能な__libraries__に外部化する方法を示しました。最後に、__overlays__と__extensions__を使用して、APIの動作面と非動作面を拡張しました。

RAMLのモジュール化手法の詳細については、https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#modularization[RAML 1.0 spec]を参照してください。 。

このチュートリアルで使用されているAPI定義の** 完全な実装** はhttps://github.com/eugenp/tutorials/tree/master/raml/modularization[githubプロジェクト]で確認できます。

次 ** "**

https://www.baeldung.com/raml- custom-properties-with-annotations

** «** 前へ

https://www.baeldung.com/simple-raml-with-resource-types-and-traits[エリミネイト
リソースタイプと特性によるRAMLの冗長性]