1. Homepage
  2. Design Center
  3. API Designer

  4. RAML 1.0 での例の定義に関するガイド

RAML 1.0 での例の定義に関するガイド

RAML 1.0 API 仕様内の型、特性、およびリソース種別の例を外部ファイルで定義する場合、次のルールに従います。

  • 1 つの例の場合、​example​ ファセットを使用して yaml ファイルを含めるか、​examples​ ファセットを使用して .raml NamedExample フラグメントファイルを含めます。

  • 複数の例の場合、必ず ​examples​ ファセットを使用して、次のいずれかの操作を行います。

    • それぞれで個々の.yaml ファイルを参照する複数の例を定義する (ファイルごとに 1 つの例が含まれる)

    • 1 つの NamedExample フラグメントで定義された 2 つ以上の例のある raml ファイルを含める

.yaml ファイルにある 1 つの例の使用

仕様で、​example​ ファセットを使用してファイルを含めます 。yaml ファイルで、例がルートレベルにあることを確認します。

次の api.raml および fragment.yaml ファイルは、.yaml ファイルにある 1 つの例を使用する正しい方法を示しています。

api.raml
#%RAML 1.0
title: test
types:
  A:
    properties:
      givenName: string
      familyName: string
    example: !include fragment.yaml
fragment.yaml
givenName: ”Chiaki”
familyName: "Mukai"

.raml NamedExample フラグメントファイルにある 1 つの例の使用

仕様で、​example​ ファセットを使用してファイルを含めます。NamedExample フラグメントで、例がファイルのルートレベルにないことを確認します。フラグメントには、例の名前であるキーが含まれている必要があります。

次の api.raml および fragment.raml ファイルは、.raml ファイルにある 1 つの例を使用する正しい方法を示しています。

api.raml
#%RAML 1.0
title: test
types:
  A:
    properties:
      givenName: string
      familyName: string
    examples: !include fragment.raml
fragment.raml
#%RAML 1.0 NamedExample
fullName:
  givenName: ”Chiaki”
  familyName: "Mukai"

次のようなフラグメントは使用しないでください。

fragment.raml
#%RAML 1.0 NamedExample
givenName: ”Chiaki”
familyName: "Mukai"

この場合、API Designer ではヘッダーが無視されて例が使用されますが、他の RAML プロセッサーと、1 つの例のみが定義されている NamedExample フラグメントを使用して仕様を検証する場合、RAML 1.0 仕様に従ってエラーが生成されます。

.yaml ファイルにある 2 つの例の命名

仕様で、​examples​ ファセットを使用してファイルを含め、各例に名前を付けます 。yaml ファイルで、例がルートレベルにあることを確認します。

次の api.raml、fragment1.yaml、fragment2.yaml ファイルは、.yaml ファイルにある 2 つの例を使用する正しい方法を示しています。

api.raml
#%RAML 1.0
title: test
types:
  A:
    properties:
      givenName: string
      familyName: string
    examples:
      fullName: !include fragment1.yaml
      otherFullName: !include fragment2.yaml
fragment1.yaml
givenName: ”Chiaki”
familyName: "Mukai"
fragment2.yaml
givenName: "Kyung-won"
familyName: "Park"

NamedExample フラグメントにある 2 つの例の命名

仕様で、​examples​ ファセットを使用してファイルを含めます。NamedExample フラグメントで、どの例もファイルのルートレベルにないことを確認します。フラグメントには、例の各名前である 2 つのキーが含まれている必要があります。

次の api.raml および fragment.raml ファイルは、.raml ファイルにある 2 つの例を使用する正しい方法を示しています。

api.raml
#%RAML 1.0
title: test
types:
  A:
    properties:
      givenName: string
      familyName: string
    examples: !include fragment.raml
fragment.raml
#%RAML 1.0 NamedExample
fullName:
  givenName: ”Chiaki”
  familyName: "Mukai"

otherFullName:
  givenName: "Kyung-won"
  familyName: "Park"