実を言うと前回このブログエントリを書いたのは、今日のエントリへの前フリでした：もともと以下で紹介する Swagger Editor を使う様子を紹介したかったのですが、そのためには扱う題材となる API が必要でした。というわけで簡単な仕様で、かつ試験的にクロスオリジン問題を解決することのできる（←ここ大事！）REST API を Node-RED で作ってみる、というのが上記の内容でした。同様に自分で管理可能な API があればそれを使って読み替えていただいてもいいのですが、そうでない場合まずは上記エントリを参照して、この後の紹介で管理する REST API を作っておいてください。
さて本題は「REST API のドキュメントをどのように用意するか」です。REST API の仕様書として最低限必要な情報は HTTP メソッドと URL のパス、実行時に与えるパラメータ、結果、そしてその API が何をするものかをざっと紹介したものでしょうか？気が利いているものだと各パラメータ毎の必須／オプションの情報、エラー時の情報などがあったりしてより便利になります。上記の Node-RED で作った API の場合だと対象の API は１つでこんな感じでしょうか：
このドキュメントでもある程度は理解できると思いますが、もう少し便利に、というか、Swagger という標準フォーマットを使ってドキュメントを作ってみます。その際に便利なのが Swagger Editor です。Swagger Editor はここにアクセスしてオンライン版をそのまま使うこともできますし、Docker イメージやソフトウェアをダウンロードして専用環境下で利用することもできます。今回はオンライン版を使って紹介します。
Swagger Editor を開いて、API ドキュメントを yaml と呼ばれるテキストフォーマットで書いていきます。今回の例だとこんな感じでしょうか：
この内容を Swagger Editor の画面左に入力します。するとこの Swagger で定義した Open API ドキュメントが画面右に表示されます：
今回定義したのは GET /getDate という１つの API です。ここをクリックすると展開され、パラメータなどより詳しい情報が表示されます。API ドキュメントとしても便利ですが、この Swagger によるドキュメント最大の特徴は「実行できる」ことです。このページから AJAX によるリクエストを発行して API を実行します。一般的には AJAX でリモートサイトにアクセスするにはクロスドメイン問題を考慮する必要がありますが、今回用意した API は（そのための目的もあって）クロスドメインからも実行できるような HTTP レスポンスヘッダを設定しています。というわけで実行してみましょう。"Try it out" と書かれたボタンをクリックします：
するとパラメータ部分が入力可能な状態になります。今回は timestamp という必須ではないパラメータを指定できるようにしていることがわかります。とりあえずはここには何も設定せずにそのまま実行してみます：
実行するには "Execute" と書かれたボタンをクリックします。すると実行した時の curl コマンドなどと一緒に実行結果も表示されます。この API はパラメータなしで実行すると現在時刻のテキストを返すようになっており、実際に実行したタイミングの日付時刻が表示されます：
次にパラメータを指定した上で実行してみます。timestamp に 1000 と入力してみました。これはタイムスタンプの値が 1000 になる日時（1970年1月1日午前零時から1000ミリ秒後）を指定したことになります：
この状態で "Execute" ボタンをクリックすると、実行結果は 1970/01/01 00:00:01 になるはずです。API が正しく動いていることがドキュメントの中から実行して確認することができました（クロスドメイン問題を抱えたままだとここでの実行は失敗します）：
と、これが Swagger で作った API ドキュメントの魅力です。 最後にここで定義した Swagger ドキュメントをエクスポートして（Swagger Editor 上ではない）別のサーバー上でも動くようにしてみます。今回は Node.js 上で実行できるような形式でエクスポートしてみましょう（サーバーサイド JavaScript である Node.js 上で実行する場合はクロスドメインは意識する必要がありません）。画面メニューの "Generate Server" から "nodejs-server" を選択します。すると自動的にダウンロードが始まり、nodejs-server-server-generate.zip というファイルがダウンロードされます：
この zip ファイルを Node.js がインストールされたシステム上に展開し、"npm install" 後に "npm run start" すると起動します：
起動したドキュメントページ（上記例だと http://localhost:8080/docs）にアクセスすると Swagger Editor の右ペインでプレビューとして見ていた部分が表示されます：
実際にパラメータを指定するなどして実行することも可能です：
以上、自分で作った API に対する実際に動かせる Swagger ドキュメントを作り、そのドキュメントを自分のサーバー上で動かす、という一連の手順を紹介しました。開発者としては API の仕様書を読み解くだけでなく、実際に動かして返ってくる値やそのフォーマットを確認しながら利用できるので、自分が API を使って作ったアプリがうまく動かなかった時の問題切り分けにも使えるツールになるので非常に便利です。
さて本題は「REST API のドキュメントをどのように用意するか」です。REST API の仕様書として最低限必要な情報は HTTP メソッドと URL のパス、実行時に与えるパラメータ、結果、そしてその API が何をするものかをざっと紹介したものでしょうか？気が利いているものだと各パラメータ毎の必須／オプションの情報、エラー時の情報などがあったりしてより便利になります。上記の Node-RED で作った API の場合だと対象の API は１つでこんな感じでしょうか：
| メソッド | パス | パラメータの指定方法 | パラメータとその意味 | 実行例 | 結果の Content-Type | 結果 |
|---|---|---|---|---|---|---|
| GET | /getDate | URLパラメータ | timestamp : タイムスタンプ値（オプション、未指定時は現在時刻） | curl -XGET 'http://xxx.com/getDate?timestamp=1000' | text/plain | 指定した日付時刻の文字列 |
このドキュメントでもある程度は理解できると思いますが、もう少し便利に、というか、Swagger という標準フォーマットを使ってドキュメントを作ってみます。その際に便利なのが Swagger Editor です。Swagger Editor はここにアクセスしてオンライン版をそのまま使うこともできますし、Docker イメージやソフトウェアをダウンロードして専用環境下で利用することもできます。今回はオンライン版を使って紹介します。
Swagger Editor を開いて、API ドキュメントを yaml と呼ばれるテキストフォーマットで書いていきます。今回の例だとこんな感じでしょうか：
swagger: "2.0"
info:
description: "俺の API"
version: "0.0.1"
title: "俺の API"
host: "**********.mybluemix.net"
basePath: "/"
tags:
- name: "myapi"
description: "俺のAPI"
schemes:
- "http"
- "https"
paths:
/getDate:
get:
tags:
- "myapi"
summary: "時刻を文字列で取得する"
description: "現在時刻または指定したタイムスタンプ値の日付文字列を返す"
produces:
- "text/plain"
parameters:
- in: "query"
name: "timestamp"
type: "number"
format: "integer"
description: "タイムスタンプ値"
responses:
200:
description: "成功"
この内容を Swagger Editor の画面左に入力します。するとこの Swagger で定義した Open API ドキュメントが画面右に表示されます：
今回定義したのは GET /getDate という１つの API です。ここをクリックすると展開され、パラメータなどより詳しい情報が表示されます。API ドキュメントとしても便利ですが、この Swagger によるドキュメント最大の特徴は「実行できる」ことです。このページから AJAX によるリクエストを発行して API を実行します。一般的には AJAX でリモートサイトにアクセスするにはクロスドメイン問題を考慮する必要がありますが、今回用意した API は（そのための目的もあって）クロスドメインからも実行できるような HTTP レスポンスヘッダを設定しています。というわけで実行してみましょう。"Try it out" と書かれたボタンをクリックします：
するとパラメータ部分が入力可能な状態になります。今回は timestamp という必須ではないパラメータを指定できるようにしていることがわかります。とりあえずはここには何も設定せずにそのまま実行してみます：
実行するには "Execute" と書かれたボタンをクリックします。すると実行した時の curl コマンドなどと一緒に実行結果も表示されます。この API はパラメータなしで実行すると現在時刻のテキストを返すようになっており、実際に実行したタイミングの日付時刻が表示されます：
次にパラメータを指定した上で実行してみます。timestamp に 1000 と入力してみました。これはタイムスタンプの値が 1000 になる日時（1970年1月1日午前零時から1000ミリ秒後）を指定したことになります：
この状態で "Execute" ボタンをクリックすると、実行結果は 1970/01/01 00:00:01 になるはずです。API が正しく動いていることがドキュメントの中から実行して確認することができました（クロスドメイン問題を抱えたままだとここでの実行は失敗します）：
と、これが Swagger で作った API ドキュメントの魅力です。 最後にここで定義した Swagger ドキュメントをエクスポートして（Swagger Editor 上ではない）別のサーバー上でも動くようにしてみます。今回は Node.js 上で実行できるような形式でエクスポートしてみましょう（サーバーサイド JavaScript である Node.js 上で実行する場合はクロスドメインは意識する必要がありません）。画面メニューの "Generate Server" から "nodejs-server" を選択します。すると自動的にダウンロードが始まり、nodejs-server-server-generate.zip というファイルがダウンロードされます：
この zip ファイルを Node.js がインストールされたシステム上に展開し、"npm install" 後に "npm run start" すると起動します：
$ cd nodejs-server-server $ npm install $ npm run start > api@0.0.1 prestart /home/pi/src/nodejs-server-server > npm install up to date in 5.819s > api@0.0.1 start /home/pi/src/nodejs-server-server > node index.js Your server is listening on port 8080 (http://localhost:8080) Swagger-ui is available on http://localhost:8080/docs
起動したドキュメントページ（上記例だと http://localhost:8080/docs）にアクセスすると Swagger Editor の右ペインでプレビューとして見ていた部分が表示されます：
実際にパラメータを指定するなどして実行することも可能です：
以上、自分で作った API に対する実際に動かせる Swagger ドキュメントを作り、そのドキュメントを自分のサーバー上で動かす、という一連の手順を紹介しました。開発者としては API の仕様書を読み解くだけでなく、実際に動かして返ってくる値やそのフォーマットを確認しながら利用できるので、自分が API を使って作ったアプリがうまく動かなかった時の問題切り分けにも使えるツールになるので非常に便利です。
コメント