Swagger UIの準備

【連載】

Swagger入門 - 初めてのAPI仕様管理講座

【第2回】Swagger UIの準備

[2017/02/20 08:30]正野 勇嗣 ブックマーク ブックマーク

開発ソフトウェア

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

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

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

Swaggerツール群の関係性(第一回の再掲)

インストールと設定

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

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

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

Swagger UI画面

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

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

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

pet 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を実行します。

/pet/findByStatus APIのインタフェース仕様

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

/pet/findByStatus API実行結果

細やかな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を紹介します。

著者紹介


正野 勇嗣 (SHONO Yuji ) - NTTデータ シニア・エキスパート

2011年頃まで開発自動化技術のR&Dに従事。その後、開発プロジェクト支援やトラブルシューティング等に主戦場を移す。「ソースコード自動生成」に加えて、JenkinsやMaven等の「ビルド自動化」、JsTestDriverやSelenium等の「テスト自動化」を扱うようになり、多様化する開発自動化技術動向に興味。

最近は第四の自動化であるInfrastructure as Code等の「基盤自動化」の魅力に惹かれている。開発自動化技術に関する雑誌・記事執筆も行う。2児のパパ。

※ 本記事は掲載時点の情報であり、最新のものとは異なる場合がございます。予めご了承ください。

関連リンク

この記事に興味を持ったら"いいね!"を Click
Facebook で IT Search+ の人気記事をお届けします
2458
2
【連載】Swagger入門 - 初めてのAPI仕様管理講座 [2] Swagger UIの準備
今回はSwagger UIを紹介します。Swagger Specで記述したYAMLやJSONファイルからAPIインタフェース仕様ドキュメントを自動生成できるツールです。ドキュメントはWebブラウザで閲覧でき、仕様を確認したら、そのままワンクリックでAPIを実行できます。
https://news.mynavi.jp/itsearch/2017/02/17/Swagger2/swaggerrec.jpg
今回はSwagger UIを紹介します。Swagger Specで記述したYAMLやJSONファイルからAPIインタフェース仕様ドキュメントを自動生成できるツールです。ドキュメントはWebブラウザで閲覧でき、仕様を確認したら、そのままワンクリックでAPIを実行できます。

会員登録(無料)

一覧はこちら

今注目のIT用語の意味を事典でチェック!

一覧はこちら

ページの先頭に戻る