API 仕様へのサンプルの追加

Exchange からの取得した、データ型と例の API フラグメントを American Flights API 仕様に追加します。その後、仕様の独自の例を作成し、応答のカスタムメッセージを追加します。

始める前に

American Flights API 仕様の設計のすべての手順を完了します。

Exchange からのフラグメントをプロジェクトに追加する

フラグメントをプロジェクトディレクトリに追加して、フラグメントを仕様に含めることができるようにします。

フライトの定義に対応するオブジェクトの Training: American Flight Data Type (トレーニング: American Flight データ型) フラグメント
API から返されるデータの Training: American Flights Example (トレーニング: American Flights の例) フラグメント

フラグメントを追加する手順は、次のとおりです。

Anypoint Code Builder で American Flights API 仕様 (american-flights-api.raml) を開きます。
コマンドパレットを開きます。
手順を表示
- キーボードショートカットを使用する。
  
  Mac: Cmd+Shift+p
  
  Windows: Ctrl+Shift+p
- デスクトップ IDE で、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。
- クラウド IDE で、 (メニュー) アイコンをクリックし、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。

次のコマンドを入力します。

MuleSoft: Add fragment dependency from Exchange

プロンプトが表示されたら、Anypoint Platform にログインして、アセットをダウンロードできるようにします。
[Search for Asset (アセットを検索)] 項目で、追加するデータ型アセットの名前を指定します。
```
Training: American Flight Data Type
```
[Assets From Exchange (Exchange のアセット)] メニューからアセットを選択します。
アセットの最新バージョン (v1.0.1 など) を選択します。

IDE でフラグメントが連動関係として追加されます。プロセスが完了したら、[Explorer] の [Project Dependencies (プロジェクト連動関係)] 領域で AmericanFlightDataType.raml アセットを確認します。次に例を示します。

での Exchange からのフラグメント"]

連動関係は、[Explorer] のプロジェクトディレクトリにある、プロジェクトの exchange.json ファイルにもリストされています。
コマンドパレットから別のフラグメントを追加します。
```
MuleSoft: Add fragment dependency from Exchange
```
追加するアセットの名前を指定します。
```
Training: American Flights Example
```
[American Flights Example (American Flights の例)] アセットの最新バージョンを選択します。

IDE でフラグメントが連動関係として [Project Dependencies (プロジェクト連動関係)] および exchange.json に追加されます。
仕様にフラグメントを挿入するに進みます。

仕様にフラグメントを挿入する

!include ディレクティブを使用してフラグメントを仕様に追加します。

AmericanFlight データ型は AmericanFlightDataType.raml で定義します。
AmericanFlightsExample.raml の例は、get 要求に対する 200 応答の例です。

フラグメントを含める手順は、次のとおりです。

[Explorer] のプロジェクトディレクトリから american-flight-api.raml を開きます。

既存のコンテンツを次のコードで置き換えます。

#%RAML 1.0
title: American Flights API

types: (1)
  AmericanFlight: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flight-data-type/1.0.1/AmericanFlightDataType.raml

/flights:
  get:
    queryParameters:
      destination:
        required: false
        enum:
          - SFO
          - LAX
          - CLE
    responses:
      200:
        body:
          application/json:  (2)
            type: AmericanFlight[]
            examples: (3)
              output: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flights-example/1.0.1/AmericanFlightsExample.raml

  post:

  /{ID}:
    get:

1	`!include` を使用して、`AmericanFlightDataType.raml` から `AmericanFlight` オブジェクトをデータ型として追加します組み込み関数を使用して、`!include` ディレクティブと仕様ファイルからのファイルパスを挿入することもできます。次に例を示します。 `「AmericanFlight: 」` (末尾のスペースを含む) と入力したら、Ctrl+Spacebar をクリックし、`「!include」`の入力を開始して、RAML ファイルのドロップダウンメニューから `[!include]` を選択します。次に例を示します。同じプロセスに従って例を追加します。`exchange_modules` ディレクトリを選択し、ステップごとに `AmericanFlightsDataType.raml` まで進みます。次に例を示します。
2	JSON (`application/json`) へのレスポンスボディの形式を設定し、応答の種別を `AmericanFlight` オブジェクトの配列 (`AmericanFlight[]`) として設定します
3	`AmericanFlightsExample.raml` の例を追加します

フライト ID による Get 要求の例を作成して含めるに進みます。

フライト ID による Get 要求の例を作成して含める

post 応答の例を作成して仕様に含めます。

[Explorer] で空の領域を右クリックして、examples という名前のフォルダーを作成します。
examples フォルダーを右クリックして、AmericanFlightExample.raml という名前の新しいファイルを作成します。

開いているファイルで次の例を追加します。

#%RAML 1.0 NamedExample
value:
    ID: 1
    code: ER38sd
    price: 400
    departureDate: 2017/07/26
    origin: CLE
    destination: SFO
    emptySeats: 0
    plane:
      type: Boeing 737
      totalSeats: 150

american-flights-api.raml ファイルに戻り、応答の /{ID}/get の下に一連の要素を作成します。

#%RAML 1.0
title: American Flights API

types:
  AmericanFlight: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flight-data-type/1.0.1/AmericanFlightDataType.raml

/flights:
  get:
    queryParameters:
      destination:
        required: false
        enum:
          - SFO
          - LAX
          - CLE
    responses:
      200:
        body:
          application/json:
            type: AmericanFlight[]
  post:

  /{ID}:
    get:
      responses: (1)
        200:
          body: (2)
            application/json:
              type: AmericanFlight
              examples: (3)
                output: !include examples/AmericanFlightExample.raml

1	`200` コードの応答を追加します
2	get リクエストボディの JSON 形式と種別 (`AmericanFlight`) を指定します
3	`/examples` ディレクトリからの例をリクエストボディのコンテンツとして追加します

Post メソッドの例を作成するに進みます。

Post メソッドの例を作成する

post 要求の例を定義します。

/flights:post メソッドへの要求では AmericanFlight 種別のオブジェクトが必要であることを指定します。

#%RAML 1.0
title: American Flights API

types:
  AmericanFlight: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flight-data-type/1.0.1/AmericanFlightDataType.raml

/flights:
  get:
    queryParameters:
      destination:
        required: false
        enum:
          - SFO
          - LAX
          - CLE
    responses:
      200:
        body:
          application/json:
            type: AmericanFlight[]
  post:
    body: (1)
      application/json:
        type: AmericanFlight (2)

  /{ID}:
    get:
      responses:
        200:
          body:
            application/json:
              type: AmericanFlight
              examples:
                output: !include examples/AmericanFlightExample.raml

1	`post` メソッドの JSON 形式のボディを指定します
2	`AmericanFlight` を `post` メソッドの種別として設定します

/examples フォルダーの下に AmericanFlightNoIDExample.raml という名前のファイルを作成し、そのファイルに次の例をコピーします。
```
#%RAML 1.0 NamedExample
value:
    code: ER38sd
    price: 400
    departureDate: 2017/07/26
    origin: CLE
    destination: SFO
    emptySeats: 0
    plane:
      type: Boeing 737
      totalSeats: 150
```
新しいフライトレコードをシミュレートするために、この例では ID パラメーターを提供していません。

american-flights-api.raml ファイルで、この例を post メソッドへの応答として追加し、カスタムメッセージを含めます。

5 の !include ディレクティブに注意してください。

#%RAML 1.0
title: American Flights API

types:
    AmericanFlight: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flight-data-type/1.0.1/AmericanFlightDataType.raml

/flights:
  get:
    queryParameters: (1)
      destination:
        required: false
        enum:
          - SFO
          - LAX
          - CLE
    responses: (2)
      200:
        body:
          application/json:
            type: AmericanFlight[]
            examples:
              output: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flights-example/1.0.1/AmericanFlightsExample.raml

  post:
    body:
      application/json:
        type: AmericanFlight
        examples: (3)
          input: !include examples/AmericanFlightNoIDExample.raml
    responses:
      201:
        body:
          application/json: (4)
            example:
              message: Flight added (but not really)

  /{ID}:
    get:
      responses:
        200:
          body:
            application/json: (5)
              type: AmericanFlight
              examples:
                output: !include examples/AmericanFlightExample.raml

1	目的地を選択します。
2	この目的地の `AmericanFlight` オブジェクトの配列を返します。
3	`examples/AmericanFlightNoIDExample.raml` から `AmericanFlight` オブジェクトを投稿します。
4	`post` メソッドへの JSON 形式の応答でカスタムメッセージを指定します
5	`examples/AmericanFlightExample.raml` からの例をネストされた `get` 要求への応答として追加します

test-api-specification.adocに進み、API エンドポイントをテストします。

ガートナーが MuleSoft をリーダーとして評価

Salesforce のフルパワーを解放する API 活用術

Anypoint Platform：開発基礎 (無料)

MuleSoft Forum Japan