SwaggerでREST APIを記述することについて僕が思うこと

これは、 TECHSCORE Advent Calendar 2016 TECHSCORE BLOG の19日目の記事です。

最近、弊社のとあるプロジェクトでSwaggerを使い始めました。Swaggerとは、簡単に言ってしまうとREST APIを記述するルール(Swagger Specification)とそれに関連するツール群です。

当然ながら、Swaggerを使わなくてもREST APIの仕様を書くことはできます（たとえばExcelなどで）。

新しい技術を導入する場合、学習コストはかかりますしいろいろと苦労することが多いのが常ですが、どうしてわざわざSwaggerを使うのでしょうか。Swaggerを使うと何がうれしいのでしょう。

Swaggerを使ってうれしいこと

Swaggerとそれら(たとえばExcelを使った場合)の大きな違いは、「REST APIの仕様を記述するルール（フォーマット）があらかじめ定められている点」、そして「コンピュータと人間が扱いやすいYAMLやJSONで書かれる点」にあります。

ルールに従ってREST APIの仕様を記述することで、仕様やドキュメントが内容として必要十分になると同時に、開発者同士もしくはサービス提供者と利用者の間でコミュニケーションが取りやすくなります。一定のルールにもとづいて記述されたREST APIの仕様は、理解しやすく議論のベースにもなります。

また、YAMLやJSONで書かれることによって、記述されたAPIの仕様を各種ツールから扱うことを容易にします。

Swaggerでは、Swagger EditorやSwagger UIなどのツールを使うことで、ドキュメントの生成やAPIの実行、さらにはクライアントSDKやサーバ側の実装のひな形を生成することが可能です。

例として、Swagger Editorを見てみましょう。
（画像はSwagger Editorのトップページから引用）

左側がユーザの記述するYAMLで、右側がそこから生成されたドキュメントです（画像だけだと分かりにくいと思いますので、こちらから実際の画面をご覧ください。）

左側でYAMLを編集していくと、リアルタイムに右側のドキュメントが更新されていくので、結果を確認しながら編集することができます。

また、この画面からAPIの実行やコードの生成も実行可能です。

このように、ツールを使いこなすことで、開発者はより価値の高い作業のほうへ集中できるようになります（各言語ごとのクライアントSDKを自動生成できるのは、うれしいですよね？）。

それ以外のSwaggerを利用するメリットとしては、Swaggerで書かれたAPIの仕様は通常テキストファイルとして保存されるため、バージョン管理システムと相性が良く差分の確認が容易です。

安心してSwaggerを使って良い？

REST APIの仕様の記述の標準化を目指すOpen API Initiative(GoogleやMicrosoft、IBMが参加)や、AWSのAmazon API GatewayではSwaggerが採用されているので、実績はあると言えるでしょう。

使ってみた感覚的には、APIの仕様を記述し、ドキュメントを生成するのは問題なく実行できます。ただし、コード生成(Swagger Codegenというツールを使います)は、まだ発展途上の印象を受けました。バージョンごとの変更が多く、バグの報告も多いように見受けられます。（実際いくつか踏みました）

Swaggerと同じ目的で使える仕様・ツールとしては、RAMLとAPI Blueprintがメジャーなようですが、Swaggerがもっとも普及しているようです（Googleでの検索結果やGoogle Trendsを見ると）。

おわりに

はじめてSwaggerを調べた時、それがいったいどういうものなのか、なかなか捉えることができませんでした。

SwaggerはREST APIの仕様を記述するためのルールとそれを扱うツール群から成り立っていて、その二つの関係を頭の中で上手く整理できていなかったためだと思います。

"API Description Languages"という言葉があるにはあるようで、Swaggerもそこに分類されていたりしますが、SwaggerはAPIを記述する言語（ルール）とツールを合わせたエコシステムが特徴的です。Swagger自身としてもそこを強みとして推している感じがします。

ただ、Swaggerの公式サイトのトップページにあるように、「THE WORLD'S MOST POPULAR API FRAMEWORK」といわれてしまうと、なんだかよく分からなくなってしまうのでした。