1前書き

今回の記事では、RAMLに関する4回目の記事、RESTful APIモデリング言語 – で、

注釈を使用してRAML API仕様のカスタムプロパティを定義する方法

について説明します。このプロセスは、仕様のメタデータの拡張とも呼ばれます。


Annotations

は公式言語の範囲外にある追加の仕様を必要とするRAML処理ツールのためのフックを提供するために使われるかもしれません。


2注釈型を宣言する

最上位の

annotationTypes

プロパティを使って、1つ以上の

annotation types

を宣言できます。

最も単純なケースでは、

アノテーション型name

はそれを指定するのに必要なものすべてです。

annotationTypes:
  simpleImplicitStringValueType:

これは、ここに示すより明示的な注釈型定義と同じです。

annotationTypes:
  simpleExplicitStringValueType:
    type: string

それ以外の場合、

annotation type

specificationには、__アノテーション型宣言と見なされる値オブジェクトが含まれます。

これらの場合、

annotation type



data type

と同じ構文を使用して定義され、2つのオプション属性が追加されます。


allowedTargets

、その値は

annotation

が適用されるターゲットロケーションのタイプを制限する文字列または文字列の配列、および

allowMultiple

はそのブール値が

annotation

が単一のターゲット内で複数回適用されるかどうかを示します(デフォルトは

false

)です。

以下は、追加のプロパティと属性を含む

annotation type

を宣言する簡単な例です。

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


2.1. 注釈の使用をサポートしているターゲットの場所


Annotations

は、API自体のルートレベル、

リソースタイプ



データタイプ



セキュリティ項目



ライブラリ



オーバーレイ



拡張子

、およびその他のアノテーションタイプ__など、いくつかのルートレベルのターゲットロケーションに適用できます。

注釈は、セキュリティスキームの設定、リソース、メソッド、応答の宣言、要求の本文、応答の本文、および名前付きの例にも適用できます。


2.2. 注釈タイプのターゲットを制限する


annotation type

を1つ以上の特定のターゲットロケーションタイプに制限するには、その

allowedTargets

属性を定義します。


annotation type

を単一のターゲットロケーションタイプに制限する場合は、

allowedTargets

属性にそのターゲットロケーションタイプを表す文字列値を割り当てます。

annotationTypes:
  supportsOnlyOneTargetLocationType:
    allowedTargets: TypeDeclaration


annotation type

に対して複数のターゲットロケーションタイプを許可するには、

allowedTargets

属性にそれらのターゲットロケーションタイプを表す文字列値の配列を割り当てます。

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

__allowedTargets__属性が__annotation type__で定義されていない場合、デフォルトでは、その__annotation type__はサポートしているターゲットロケーションタイプのいずれにも適用できます。

[[applying]]

===  **  3注釈型を適用する**

RAML API仕様のルートレベルで__annotation types__を定義したら、それらを目的のターゲットの場所に適用し、各インスタンスでプロパティ値を指定します。ターゲットロケーション内の「アノテーションタイプ」の適用は、単にそのターゲットロケーション上の「アノテーション」と呼ばれます。

====  **  3.1. 構文**

__annotation type__を適用するには、ターゲットの場所の属性として、かっこ()で囲まれた__annotation type name__を追加し、__annotation type__がその特定のターゲットに使用する__annotation type value__プロパティを指定します。 __annotation type__がRAML __library__にある場合は、__library__参照の後にドット(。)を続け、その後に__annotation type nameを連結します。

====  **  3.2. 例**

上記のコードスニペットにリストされている__アノテーションの種類__をAPIのさまざまな__resources__と__methods__に適用する方法を示す例を示します。

[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使用事例


annotations

の潜在的なユースケースの1つは、APIのテストケースの定義と設定です。


annotations

に基づいて、APIに対して一連のテストを生成できるRAML処理ツールを開発したいとします。以下の

アノテーションタイプ

を定義することができます:

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

次のように__annotations__を適用することで、__/foos__リソース用の一連のテストケースを構成できます。

[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結論

このチュートリアルでは、

annotations

というカスタムプロパティを使用してRAML API仕様のメタデータを拡張する方法を示しました。

最初に、最上位の

annotationTypes

プロパティを使用して

annotation types

を宣言する方法を示し、それらが適用されることを許可されているターゲットロケーションのタイプを列挙しました。

次に、私たちのAPIで

annotations

を適用する方法を説明し、与えられた

annotation

を適用することができるターゲットロケーションのタイプを制限する方法に注目しました。

最後に、テスト生成ツールで潜在的にサポートされる可能性がある

annotation types

を定義し、それらの

annotations

をどのようにAPIに適用できるかを示すことによって、潜在的なユースケースを紹介しました。

RAMLでの

annotations

の使用に関する詳細は、https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/#annotations[RAMLをご覧ください。 1.0仕様]。

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

  • «** 前へ