ブログトップ 記事一覧 ログイン 無料ブログ開設

Groovyラボ RSSフィード

2014-12-01

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なので気をつけてください)

f:id:ksky:20141201221558j:image

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好きならば今のうちに試してみる価値はありますよ!

はてなユーザーのみコメントできます。はてなへログインもしくは新規登録をおこなってください。

トラックバック - http://d.hatena.ne.jp/ksky/20141201/p1