RESTful APIの記述標準化を目指す「Open API Initiative」をマイクロソフト、Google、IBMらが立ち上げ。Swaggerをベースに － Publickey で紹介されているように、Open API Initiativeが立ち上がって、Swaggerの2.0をベースに RESTful API の記述標準化が始まった。まだ openapis.org に仕様は書かれておらず、Swagger 見てね、という状態。
RESTful API が何かはだいたい分かっているものとして、それを標準化するというのはどういうことか、何が便利になるのか。
まず、API を作る側のドキュメンテーション作業が楽になる。
などで紹介されているように、Swagger は json や yaml で API の仕様を書くことでHTMLのドキュメンテーションが自動化できるようになっている。
例えば、
のような json を Swagger で読み込むと
のようなページが作成され、そこで様々なAPIコールを試したりもできるようになっている。
API を作る側のドキュメンテーション作業が楽になるということは、使う側が得られるドキュメンテーションのクオリティが平均的に高くなるということも意味する。現在、このような API コールを試したりできる説明ページを提供している API は多くない。
そして、この仕様を記述する json は Specification | Swagger のページに書かれているように記述フォーマットが定められている。現段階では、名だたる大企業が、このフォーマットを標準化のベースにしますというお墨付きを与えたということになる。
json というデータフォーマットで記述するため言語に非依存で書けるが、それぞれの言語ごとにライブラリでサポートされていたりする。より正確に言えば、言語ごとというより、ウェブフレームワークのようなレベルでサポートされていたりする。言語が nodejs ならば Node.js - swagger-expressを使って簡単にAPIドキュメントを作成する - Qiita で紹介されているようにウェブフレームワークである express 用のライブラリが提供されている。結局プログラムのコメントに yaml で書き込んだり、プログラム内にjsonで値を定義したりしている場合が多いので、あまり労力は変わっていないのだが、コードのメンテ上の利便性の面では API のコードとドキュメンテーションを対応付けて書いておいた方が良いかもしれない。
サーバアプリで既存の使用例としては、データ管理のプラットフォーム Girder で使えるようになっていて、kitware.com上のデモでその動きを確認できる。
参考:
- 5分で絶対に分かるAPI設計の考え方とポイント (6/6) - ＠IT 末尾で Swagger 以外のツールも紹介されている。
- Swaggerで始めるモデルファーストなAPI開発 Swagger 関連ツールの使い方などが書かれている。めんどくさいよね、という印象。
- WebAPI - Web APIにはJSONベースのフォーマットを使おう - Qiita JSON のフォーマットとして HAL, JSON API(固有仕様の名前), Collection+JSON が紹介されている。本来は JSON を使ったデータ表現の形式だが、十分汎用的な JSON-LD が普及してくれればよいなと個人的には思う。
- JSONスキーマはじめの一歩 - Qiita JSON スキーマも近い概念
- APIドキュメントを支える技術 - Qiita 比較
- jsonschema - How to generate JSON-Schema from Swagger API Declaration - Stack Overflow Swagger から JSON Schema とるのは難しいよ
- Specification | Swagger にも JSON Schema は出てくる。つまり共通点は多い
- RE: How does JSON-LD relate to JSON Schema? from Markus Lanthaler on 2014-10-06 (public-linked-json@w3.org from October 2014) JSON Schema は JSON-LD のスキーマとして併用することもできる。
