Swagger UIの準備

今回はSwagger UIを紹介します。

Swagger UIは、Swagger Specで記述したYAMLやJSONファイルからAPIインタフェース仕様ドキュメントを自動生成できるツールです。ドキュメントはWebブラウザで閲覧でき、仕様を確認したら、そのままワンクリックでAPIを実行できます。

HTMLやCSS・Javascriptなどの形式で出力されていますので、見た目や動作を細やかにカスタマイズ可能な点も見逃せません。今回紹介するインストールから動作確認までの手順をぜひ試してみてください。

インストールと設定

ターミナルにてgit cloneコマンドを入力し、Swagger UIをインストールします。

$git clone https://github.com/swagger-api/swagger-ui.git

実はインストール作業はこれで終わりです。クローンしたフォルダのdist/index.htmlをWeb Webブラウザから開くと以下の画面が表示されます。なお、distフォルダをアプリケーションサーバなどにデプロイしても構いません。

初期状態では、Swagger PetstoreのSwagger SpecをベースにしたAPIが表示されています。別のAPIを指定する場合は赤枠部分に別のファイルを指定し、Exploreボタンをクリックすることで切り替え可能です。

機能紹介と基本的な使い方

上図[pet : Everything about your Pets]の[Show/Hide]をクリックします。以下の通りSwagger Specで定義されているAPIの一覧が表示されます。

用意されているメソッドは、データベースの世界で言うところのCRUD(Create/Read/Update/Delete)に相当し、例えばGETはRead、PUTはUpdateといった形です。また/pet/{petId}といった形でRESTのパス(URL)を示しており、{perId}は変数に相当します。 今回は、[/pet/findByStatus]をクリックし、APIの仕様を表示します。

以下の通り、APIの説明(Implementation Notes)や、モデルのサンプル値(ModelのExample Value)など、APIの仕様を確認できます。[Parameters]-[Parameter]-[status]-[available]を選択した上で、[Try it out!]をクリックし、APIを実行します。

以下の通り、実行結果が表示されます。<pets>-<Pet>-<id>が59で、<pets>-<Pet>-<name>がdoggieのペットが返却されました。

細やかなAPIドキュメンテーション

前節で触っていただいたSwagger UIについては、HTMLやJavaScriptの組み合わせですので、下表の要素を細かく設定可能です。

表:カスタマイズポイント

フォルダ	カスタマイズポイント
dist	ディストリビューション
dist/lang	swaggerローカライゼーション
lib	javascriptライブラリ
node_modules	nodeモジュール
src/main/template	htmlテンプレート
src/main/html	HTML、イメージ、CSS
src/main/javascript	メインのJavascriptコード
src/main/less	LESS(CSSへコンバート)

例えば、src/main/html/index.htmlの<span class=”logo__title”>の要素を、以下のように[swagger]から[swagger入門]に変更します。

<div id='header'>
  <div class="swagger-ui-wrap">
    <a id="logo" href="http://swagger.io"><img class="logo__img" alt="swagger" height="30" width="30" src="images/logo_small.png" /><span class="logo__title">swagger入門</span></a>
    <form id='api_selector'>
      <div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div>
      <div id='auth_container'></div>
      <div class='input'><a id="explore" class="header__btn" href="#" data-sw-translate>Explore</a></div>
    </form>
  </div>
</div>

カスタマイズを実施したら以下のコマンドにて再ビルドします。カスタマイズしたファイルはdistフォルダにコピーされます。また、lessファイルはcssファイルに変換された上でコピーされます。

$ npm install
$ npm run build

> swagger-ui@2.2.8 build /Users/yujishono/swagger/swagger-ui
> npm run handlebars && gulp
> swagger-ui@2.2.8 handlebars /Users/yujishono/swagger/swagger-ui
> handlebars ./src/main/template -f ./src/main/template/templates.js && gulp handlebars

[21:55:49] Using gulpfile ~/swagger/swagger-ui/gulpfile.js
[21:55:49] Starting 'handlebars'...
[21:55:49] Finished 'handlebars' after 19 ms
[21:55:51] Using gulpfile ~/swagger/swagger-ui/gulpfile.js
[21:55:51] Starting 'default'...
[21:55:51] Starting 'clean'...
[21:55:51] Starting 'lint'...
[21:55:51] Finished 'clean' after 183 ms
[21:55:51] Starting 'less'...
[21:55:51] Finished 'less' after 376 ms
[21:55:51] Starting 'copy'...
[21:55:51] Finished 'copy' after 4.17 ms
[21:55:51] Finished 'lint' after 907 ms
[21:55:51] Starting 'dist'...
[21:56:00] Finished 'dist' after 8.25 s
[21:56:00] Starting 'uglify-libs'...
[21:56:00] Finished 'uglify-libs' after 1.63 ms
[21:56:00] Starting 'minify-css'...
[21:56:05] Finished 'minify-css' after 5.27 s
[21:56:05] Finished 'default' after 14 s

再度Webブラウザからアクセスすると、以下のとおり、タイトルが[swagger]から[swagger入門]に変更されました。

*　　*　　*

今回はSwagger UIを紹介しました。Swagger UIは、インストール方法が極めてシンプルです。Webブラウザで閲覧できる形式のため、ドキュメントの公開が容易です。APIエコノミーが進展する状況においては、APIの公開に歩調を合わせることが可能となります。

Swagger UIはDockerを使って環境を汚さずに構築することも可能です。API間の依存関係を見える化するZipkinなど、近年のツールはDockerを前提としてインストール可能なものが増えてきています。数ステップで極めて簡単にインストール可能ですので、併せて試してみてはいかがでしょうか。

次回は実際に動作するAPIのクライアントおよびサーバのソースを自動生成するSwagger Codegenを紹介します。