Skip to content

Swagger Definitions

Jump to bottom
TakayukiHoshi1984 edited this page Mar 28, 2019 · 2 revisions

Device Connect API の仕様は Swagger 2.0 を独自拡張した形式で定義されます。 以下の節で、独自拡張した部分について説明します。

必須事項

Swagger 2.0 で Device Connect API を定義する上で、必ず記述する必要のある項目について説明します。

operationId

Operation Object の operationId は API の識別子を記述するプロパティです。 Swagger 2.0 上では任意で指定可能なパラメータですが、Device Connect API を定義する際は必ず指定してください。

命名規則は、以下のとおりです。

  • API のパスとメソッド名を連結した、キャメルケースの文字列
  • ただし、APIのパスから /gotapi は省きます。

例えば、POST /gotapi/someProfile/someAttribute というAPIを定義する場合、operationId は someProfileSomeAttributePost となります。

省略した場合の影響

現状では DeviceConnectCodegen に API 定義を入力する場合に影響が出ます。DeviceConnectCodegen では operationId が省略された場合は不定の文字列で補完されるため、スケルトンコードの出力自体は可能ですが、ビルド後の正常な動作は担保されません。その場合は DeviceConnectCodegen が警告を標準出力します。

x-type

x-type は API 種別を記述するためのプロパティです。Operation Object の直下に記述してください。プロパティ値には以下のいずれかを指定します。

項目 説明
one-shot ワンショットAPI。API のリクエストに対して同期的にレスポンスを返す。GET, POST, PUT, DELETE のいずれかで定義する。
event イベントAPI。PUTメソッドでイベントを登録する。DELETEメソッドでイベントの登録を解除する。イベントの「登録」とは、言い換えると、クライアントへのイベントメッセージの送信を有効にすることを指す。イベントメッセージは WebSocket 経由で非同期的に通知される。PUT と DELETE の2つの定義が必要。
streaming ストリーミングAPI。PUTメソッドでストリーミング配信サーバを起動し、そのURLを返す。DELETEメソッドで停止する。それ以外のストリーミング配信サーバの仕様はプラグイン側で独自に定義して良い。PUT と DELETE の2つの定義が必要。

x-event

x-event はイベントメッセージの仕様を定義するプロパティです。前述の x-type で event を指定した場合、PUT メソッドを定義するための Operation Object の直下に記述してください。 DELETE メソッドの方には記述しなくて構いません。

記述形式は Response Object と同一です。

例えば、 PUT /gotapi/battery/onBatteryChange の場合は以下のように記述しています。

"x-event": {
  "schema": {
    "$ref": "#/definitions/OnBatteryChangeEvent"
  },
  "examples": {
    "application/json": {
      "serviceId": "example-service-id",
      "profile": "battery",
      "attribute": "onBatteryChange",
      "battery": {
        "chargingTime": 10,
        "dischargingTime": 0,
        "level": 0.8
      }
    }
  }
}

制限事項

Swagger 2.0 で Device Connect API を定義する上で、制限を設けている項目について説明します。

パスの長さは 2 以上 4 以下 とする

Device Connect では、API のパスを、API名・プロファイル名・インターフェース名・アトリビュート名の４つの要素で定義します。 そのため、API のパスの長さ (basePath と連結後の長さ) については 2 以上 4 以下に制限されます。

（例）

  • /gotapi/someProfile
  • /gotapi/someProfile/someAttribute
  • /gotapi/someProfile/someInterface/someAttribute
Clone this wiki locally