Swaggerについて学ぶ(基礎知識編) - 前人未踏の領域へ Androidアプリ開発編

Swaggerとは

Swaggerは言語に依存しないREST APIのインターフェース仕様とそのツール群を指す。
Swaggerの仕様に沿ってAPIを定義することで、人間が理解可能で、コンピューターにも解析可能なAPI仕様書となる。

Swaggerの提供するもの

項目	概要
Swagger Specification	JSON or YAMLによるAPI記述フォーマット。バージョン、パラメータ、型、レスポンス、必須有無、対応メソッドなどの記述ルールが定義されている
Swagger UI	記述したAPI仕様を読みやすいHTMLで確認
Swagger Editor	ブラウザで利用可能な専用エディタでプレビューしながら編集
Swagger CodeGen	APIを元にサーバー、クライアント双方のAPIアクセスコードを自動生成
その他	他にも多分ある

Swaggerを使うメリット

決まったルールに従ってAPIを設計できる
0からAPIの記述ルールを決めなくていい
ビューワーもついてくるので参照、エンジニア間で共有しやすい。
テキストファイルなのでGithubなどでバージョン管理ができる
パーサーがあるので、その気になれば他のドキュメント（Wiki, Markdown

, Excel）にも変換が可能である(はず)。

コードもその気になれば生成できる（ベストなものとは限らないと思うけど）

競合の存在

同様のAPI標準化ではAPI BluePrintなどいくつかの競合が存在するが、Googleなども参加するOpen API Initiativeで基準APIフォーマットとして採択された点は将来性の面で強みとなるだろう。とはいえユーザーが選んだものがデファクトとして勝利するので、個人で使うなら自分に馴染むものを選ぶ、でいいと思う。

どこから始めるか

トップダウンアプローチ：これからAPIを書く場合、Swagger Editorを使ってAPIを書き、アクセスコードを自動生成するのがよい
ボトムアップアプローチ：既存のコードがある場合、Swagger Editorを使って APIを手書きするか、JAX-RXを使っていればSwaggerフォーマットのテキストを自動生成できる。

ツール

いろいろある。

オープンソース：http://swagger.io/open-source-integrations/
商用：http://swagger.io/commercial-tools/

まとめ

ライブラリ含め、どちらかというとJavaよりなんだけど、
API仕様自体はJavaに依存していないし、各種言語向けのコードも書き出せるので気にしなくてもいいんじゃないかと思う。
とりあえずWikiとかに適当で統一感もなく保守もされないされないようなドキュメント書いてるくらいなら
swagger仕様に合わせて仕様書作っておいて、gitでコード管理すると良いかと思う。