はじめに

この記事は foodison advent calendar 2015 の 7日目の記事です。

こんにちは。　2015年10月半ばにエンジニアとして入社しました市川です。 社内で一番料理が出来ないと自負しております。　はい。

唐突ですが、スマートフォンやタプレットへの対応のため、API を実装する機会が増えているのではと思います。

サーバサイドを API 化しておくことで、フロントエンドとバックエンドを疎結合にすることが出来、マルチデバイスへの対応が容易になる等、いくつかのメリットがあります。

反面、API の利用者側へ提供するドキュメントの管理のわずらわしさといった問題もあります。　最新のコードに追従できない。　書き手によってフォーマットに統一性が無いなどです。

この問題を解決する １つの手段として Swagger を２回に渡って紹介したいと思います。

Swagger とは

• オープンソース API フレームワーク
• JSON 形式 で API を記述するフォーマットと、記述するためのツールを提供
• RESTful API の記述標準化を目指す Open API Initiative が採用
• Amazon API Gateway 等の API ツールで採用

Microsoft、Google、IBM らが参画する Open API Initiative が採用というコトで、将来有望なのではと思います。

Swagger は、まだまだ日本語での情報も少ない上に、ツール類も多く、難解なイメージがあります。 今回は、主要なツールと公式のデモを見ながら、Swagger の概要をつかんでいきたいと思います。

Swagger Editor

ブラウザ上で API 仕様 ( swagger.json ) を作成します。

• ブラウザ上で YAML フォーマットにて API 仕様 ( swagger.json ) を 作成
• API 仕様を元に生成されるドキュメントをリアルタイムでプレビュー可能
• 生成された API 仕様 ( swagger.json ) は他のツールから利用
• ローカル環境にインストールして利用する事も可能

この API 仕様を、次で紹介するドキュメント生成ツール Swagger UI や、今回は紹介しませんが クライアントコードを自動生成する Swagger Codegen 等から利用します。

公式サイトに実行可能な デモ がありますので、試してみましょう。

画面左側に YAML フォーマットにて API 仕様を作成していきます。 フォーマットについては、公式サイトの Specification を参照してください。 画面右側でリアルタイムで構文チェックが行われ、生成されるドキュメントをプレビューすることが出来ます。 ( ※ 実際にドキュメントを生成するには Swagger UI が必要です。 )

File > Open Example… から、他のサンプルも確認する事が出来ますので、いろいろ見てみましょう。

Generate Server 、Generate Client というメニューがある通り、各言語のサーバー、クライアント用コードの雛形を生成する機能もあります。 この機能については Swagger Codegen を使っているのではと思うのですが … 違っていたらすみません 汗

Swagger UI

Swagger Editor 等により作成された API 仕様 ( swagger.json ) から見やすいドキュメントを生成します。

• Swagger 準拠の API 仕様 ( swagger.json ) からドキュメントやサンドボックスを生成
• パラメータ等を入力し、その場で API の動作をテストする事が可能
• 任意のサーバやローカル環境にインストールして利用する事が可能

公式サイトに実行可能な デモ がありますので、試してみましょう。

各 API で、リクエストのためのパラメータを入力し、左下の Try it out! ボタンを押下すると、入力したリクエストに対する、レスポンス結果を確認することができます。

その他

Swagger のエコシステムが提供してくれているツール群が公式サイトで紹介されています。

Tools & Integrations

Ruby の場合、テストツールの Apivore 、API 定義を独自の Ruby DSLで行う swagger-blocks 、API ドキュメント (Swagger UI) を Rails Engine として提供する swagger-engine が紹介されています。

おわりに

駆け足でしたが、Swagger の大枠をつかむコトが出来たでしょうか!?

次回は、Swagger UI と Swagger Editor をインストールし、作成した API ドキュメントを公開する流れを説明できたらと思います。