REST APIの仕様書を定義するとき「Swagger」より「.rest形式」がオススメな4つの理由

「Swagger」とは、REST APIを定義するためのフレームワークのひとつです。

MicrosoftやGoogle、IBM等によって立ち上げられた「Open API Initiative」という団体が、REST APIの仕様書を定義するための標準フォーマットとして、このSwaggerを推奨しています。Swagger Editorを使い独自の書式でコードを書くと、このコードを元にSwagger UIが仕様書を自動的にドキュメント化し、さらにそのドキュメントから実際のリクエストを投げることが出来ます。

このような便利なツールが提供されている事もあり、REST APIの記述における標準仕様になる可能性が高いと言われているSwaggerですが、SCOUTER開発者ブログでは下記のようなデメリットについても触れられています。

  • 独自記法を覚える必要がある
  • どうしても記述量が多くなる
  • #definitions/スキーマをモデルごとに書く必要がある
  • 細かいカラムの表示制御(あるAPIではemailを含めるが、他のAPIでは情報保護のためにemailは表示しないなど)を表現しづらい
  • API仕様書自体の保守コストがかかり、実装と違う記述になる

そして、このデメリットをふまえ「エディタのプラグインなどを利用して、.restや.httpといったファイル形式でAPI仕様書を書く」という方法を提言しています。

この方法を採用することにより、Swaggerを利用した場合と比較して、以下のようなメリットがあるとのこと。

  1. RFC7230ベースの記述により、見やすく、学習コストや自動出力の実装コストが低い
  2. ファイルの分割粒度をリクエスト単位に分けても差し支えない
  3. エディタのサポートにより、API仕様書用に環境を整備しなくていい(VimやEmacs、Atomだけでなく、2017.3 EAPからPhpStormやIntelliJIDEAなどのJetBrains系IDEにも公式導入された)
  4. ローカルファイルへ記述するためセキュリティー面で安心

SwaggerでAPI仕様書に消耗しているなら.restを使うといい。特にLaravelなら – SCOUTER開発者ブログ