TOC

アノテーションを使ってカスタムRAMLプロパティを定義する

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]で確認できます。

  • «** 前へ

Modular インクルード、ライブラリ、オーバーレイ、および拡張機能を使用したRAML

Related