Open API とは何か

調べてもいつも忘れるので、自分でまとめてみる。 API というのは（多くの IT エンジニアにとっても）身近なものなはずで、その API の “Open” な仕様というのは興味をひくキーワードではなかろうか。

Open API の概要

Open API (※1)と聞くと、何かの API サービスや API の実装に便利なライブラリなどを想像してしまいそうだが、そうではない。 Open API は、RESTful API のインタフェイス定義の記述形式を仕様化したもので、統一的な定義を用いることにより開発者間の合意を助けるだけでなく、ドキュメント生成やモック生成の自動化などにより作業効率化を図るものである。

OAI (Open API Initiative) は、Open API の策定推進のために結成された団体である。(※2) 歴史的に Open API は Swagger の仕様を移行したもので(※3)、そういった経緯で Swagger が標準的な実装となっている。

OAI のサイトが Open API Initiative で、 Open API の仕様は OpenAPI-Specification/versions at master · OAI/OpenAPI-Specification で、バージョンごとに公開されている。(※4)

※1: オフィシャルサイトでも Open と API の間にスペースがついたりつかなかったりして、どちらが正しいのかわからない。
※2: New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services – Open API Initiative
※3: 2.0 の仕様を読むと、おもむろに Swagger の名前が出てくるが、これはそういった経緯のため。
※4: Open API の（仕様を公開する）サイトというのはないようだ。 Open API は Swagger Spec から移行して間もないので、これから整備されるかもしれない。

Open API の仕様

Open API では、RESTful API のインタフェイス定義自体も JSON（もしくは YAML）で記述する。 JSON は　URL　パスごとに用意するイメージで、メソッドごとにパラメータとレスポンスの定義を記述するフィールド群と、各種メタデータを記述するフィールド群をもつオブジェクトをルートとする。

swagger: '2.0'
info:
  title: Sample API
  version: '1.0'
host: api.example.com
paths:
  /hello:
    get:
      produces:
        - application/json
      responses:
        200:
          description: OK

所感

仕様自体は必要十分な構成。 JSON と聞くと入れ子が深くなるケースが気になるが、サンプルをみる限り視認性も悪くなさそう。個人的には使う価値は十分あると思っていて、もちろん開発者間の合意という点だけなら、見やすいフォーマットであればなんでもいいんだけど、Swagger フレームワークの提供する便利な機能を含めて評価するべきで、非常に有用である。