1. 序章

この記事では、RAMLに関するシリーズの4番目の記事(RESTful APIモデリング言語)で、アノテーションを使用してRAMLAPI仕様のカスタムプロパティを定義する方法を示します。 このプロセスは、仕様のメタデータの拡張とも呼ばれます。

注釈は、公用語の範囲外にある追加の仕様を必要とするRAML処理ツールのフックを提供するために使用できます。

2. 注釈タイプの宣言

1つ以上のアノテーションタイプは、トップレベルのannotationTypesプロパティを使用して宣言できます。

最も単純なケースでは、アノテーションタイプ名がそれを指定するために必要なすべてです。この場合、アノテーションタイプ値は暗黙的に文字列として定義されます。

annotationTypes:
  simpleImplicitStringValueType:

これは、次に示す、より明示的な注釈タイプの定義と同等です。

annotationTypes:
  simpleExplicitStringValueType:
    type: string

その他の場合、アノテーションタイプ仕様には、アノテーションタイプ宣言と見なされる値オブジェクトが含まれます。

このような場合、アノテーションタイプは、データタイプと同じ構文を使用して定義され、2つのオプション属性が追加されます。文字列または注釈を適用できるターゲット位置のタイプを制限する文字列の配列、および allowMultiple 、そのブール値は注釈かどうかを示します1つのターゲット内で複数回適用できます(デフォルトは false )。

以下は、追加のプロパティと属性を含むアノテーションタイプを宣言する簡単な例です。

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

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

アノテーションは、API自体のルートレベル、リソースタイプ特性など、いくつかのルートレベルのターゲットロケーションに適用(使用)できます。 ]データ型ドキュメントアイテムセキュリティスキームライブラリオーバーレイ拡張機能、およびその他の注釈タイプ

注釈は、セキュリティスキーム設定リソースメソッド応答宣言、にも適用できます。リクエストボディレスポンスボディ、および名前付きの例

2.2. アノテーションタイプのターゲットを制限する

アノテーションタイプを1つ以上の特定のターゲットロケーションタイプに制限するには、そのallowedTargets属性を定義します。

アノテーションタイプを単一のターゲットロケーションタイプに制限する場合、allowedTargets属性にそのターゲットロケーションタイプを表す文字列値を割り当てます。

annotationTypes:
  supportsOnlyOneTargetLocationType:
    allowedTargets: TypeDeclaration

アノテーションタイプに対して複数のターゲットロケーションタイプを許可するには、 allowedTargets 属性に、それらのターゲットロケーションタイプを表す文字列値の配列を割り当てます。

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

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

3. 注釈タイプの適用

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

3.1. 構文

アノテーションタイプを適用するには、ターゲット位置の属性として括弧()で囲まれたアノテーションタイプ名を追加し、アノテーションタイプ値プロパティを指定します注釈タイプがその特定のターゲットに使用すること。 アノテーションタイプがRAMLライブラリにある場合は、ライブラリ参照、ドット(。)、アノテーションタイプを連結します。名前。

3.2. 例

上記のコードスニペットにリストされているアノテーションタイプの一部をAPIのさまざまなリソースおよびメソッドに適用する方法を示す例を次に示します。

/foos:
  type: myResourceTypes.collection
  (simpleImplicitStringValueType): alpha
  ...
  get:
    (simpleExplicitStringValueType): beta
  ...
  /{fooId}:
    type: myResourceTypes.item
    (complexValueType):
      prop1: 4
      prop2: testing
      prop3: true

4. 使用事例

アノテーションの潜在的なユースケースの1つは、APIのテストケースを定義および構成することです。

アノテーションに基づいて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[]

次に、アノテーションを次のように適用することで、 /foosリソースの一連のテストケースを構成できます。

/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. 結論

このチュートリアルでは、アノテーションと呼ばれるカスタムプロパティを使用して、RAMLAPI仕様のメタデータを拡張する方法を示しました。

最初に、トップレベルの annotationTypes プロパティを使用してアノテーションタイプを宣言する方法を示し、それらを適用できるターゲットロケーションのタイプを列挙しました。

次に、APIでアノテーションを適用する方法を示し、特定のアノテーションを適用できるターゲットの場所のタイプを制限する方法に注目しました。

最後に、テスト生成ツールでサポートされる可能性のあるアノテーションタイプを定義し、それらのアノテーションをAPIに適用する方法を示すことで、潜在的なユースケースを紹介しました。

RAMLでのアノテーションの使用の詳細については、RAML1.0仕様にアクセスしてください。

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