REST APIを記述せよ！Swagger紹介 #apijp

Web API Advent Calendar 2014、初日はSwaggerを紹介します。

SwaggerはReverbによって開発された、RestfulなAPIを記述する標準仕様です。APIを機械可読な形で記述することは、ドキュメント生成やツール開発、さまざまな形での自動化に非常に重要です。好き嫌いはともかく、SOAPにはWSDLという統一標準がありましたが、RESTには本質的にそういった標準がないため、類似するさまざまな仕様が開発されてきました。Swaggerはその中でも最も有望なものの一つだと思います。

1. 特徴

記述はJSONでシンプル。ミニマム定義の例：

{
    "swagger": "2.0",
    "info": {
        "version": "1.0.0",
        "title": "petstore"
    },
    "paths": {
        "/users": {
            "get": {
                "responses": {
                    "200": {
                        "description": "Describe the 200 response in more detail"
                    }
                }
            }
        }
    }
}

Swaggerのサイトにはブラウザ上で試せるSwagger Editorというものが用意されており、左側にAPI記述を書くと、右側に生成されるドキュメントのプレビューを見ることができます（下図）。これを少し試すとSwaggerの雰囲気がすぐつかめると思います。（APIの記述はJSONではなくYAMLなので気をつけてください）

オープンでベンダーや実装言語などに依存しない。仕様はGitHubで公開されておりApache 2.0ライセンスで利用できます。
エコシステムが充実。コミュニティによりさまざまな言語に対応した多彩なツールやライブラリが作られています。
賛同・ユーザ企業の多さ。Swagger 2.0仕様はオンラインサービスのPayPalやGetty Images、API関連企業のApigeeや3scaleを始め、500近くの大小企業の貢献で作られました。Microsoftや米政府も使っています。

2. バージョンについて

2014/09/08に最新のSwagger 2.0がリリースされました。2.0は、これまでの1.x(最新は1.2)系とは互換性がないので注意が必要です（マイグレーションガイドはこちら）。2.0がまだ出たばかりなので、web上で見つかる日本語のSwagger記事はほとんど1.x系のものです。注意してください。

3. Swagger対応の便利ツール

Postman: みんな大好きAPIテストクライアントの定番、PostmanにもSwaggerインポート機能があります（Swagger 1.2対応）。
Mockable: REST/SOAPなモックサーバを簡単に立ち上げられる期待のサービス、MockableでもSwaggerインポートをサポート予定です（現時点では未実装）。
Apigee 127: APIモデル定義をベースに、Node.jsでの実装スケルトンを生成したり、キャッシュやレートリミット、OAuthなどのAPI管理機能を簡単に実現できるオープンソースプロジェクト、Apigee 127でもSwagger 2.0が基盤技術として採用されています。

まとめ

Swaggerは現在メジャーバージョンの移行期にあるため、ツールやサポートに若干の混乱はありますが、2.0への移行完了後がとても楽しみな技術です。Web API好きならば今のうちに試してみる価値はありますよ！