Swagger が OpenAPI にリネームされて Open API Initiative が誕生してた

このニュースに気づいたのが今更で非常にお恥ずかしい限りですが、こちらの記事をご覧ください。

REST API 仕様の標準化が進むのはとても良いニュースですね。

それで、2016年1月1日に Swaggerの公式サイト にて朗報が。

Starting January 1st 2016 the Swagger Specification has been donated to to the Open API Initiative (OAI) and has been renamed to the OpenAPI Specification.

日本語に訳すと。

来る2016年1月1日に Swagger Specification は Open API Initiative (OAI) に寄贈され、 OpenAPI Specification とリネームされました。

なるほど、とりあえず Swagger 2.0 仕様は OpenAPI 2.0 仕様としてリネームされただけのようです。これなら既存の Swagger 2.0 準拠アプリも簡単に移行できそうですね!

付録: Swagger (OpenAPI) とは何か

Swagger とは、端的に説明すると REST API を設計し定義するための仕様です。

テスト駆動開発はよく知られていると思います。 Swagger を基本とした開発手法に名前を付けるのであれば、設計駆動開発 (Design Driven Development) といえるでしょう。

参考例として、 Swagger を使った 設計駆動開発の大まかな流れは以下のようになります。

  1. エディターを使い REST API を設計し定義書を作成する。定義書の実際のフォーマットは YAML または JSON である。
  2. 設計定義書のバリデーションを行う。 Swagger の仕様に沿って記述されていなければならない。
  3. 設計定義書を元に実装する。大まかな挙動やモックは自動生成できるし、入出力のチェックは Swagger に準拠したフレームワークに任せることができる。
  4. 設計定義書を元にテストを実行する。だいたいは自動生成できる。
  5. 設計定義書を元に API クライアントを生成できる。
  6. 設計定義書を元に API 利用者向けドキュメントも生成できる。

ちなみに、 TypeScript で Swagger 2.0 に準拠された REST API 定義を実装するために弊社の @mugesoswaggerize-expressType Definitions を書いてくれました。ぜひ使ってください。 tsd install swaggerize-express