Swaggerとは？OpenAPIとの違いを初心者向けに画像多めで解説！

Swaggerは、簡単に言うと、
APIの仕様書を分かりやすく作ったり、画面上で確認したり、実際に試したりするためのツール群だよ。

そう。
たとえばWeb APIには、

どのURLにアクセスするのか
GETなのかPOSTなのか
どんなパラメータを送るのか
どんなレスポンスが返ってくるのか
エラー時はどうなるのか

みたいな情報があるよね。

Swaggerは、そういうAPIの情報を整理して、人にも機械にも分かりやすい形で扱えるようにするものだよ。

APIは、アプリやシステム同士がやり取りするための窓口みたいなものだよ。

たとえば、天気アプリが天気情報を表示するとする。
アプリの中に全国の天気情報を全部持っているわけじゃなくて、天気情報を持っているサーバーに問い合わせる。

天気アプリ
↓
「東京の天気を教えて」
↓
天気API
↓
「晴れ、気温25℃です」

そうそう。
そのAPIを使うには、「どんなお願いの仕方をすればいいのか」が必要になる。
それを書いたものがAPI仕様書。

ざっくり言うと、今はこう考えるといいよ。

そう。
OpenAPI Initiativeは、OpenAPI SpecificationをHTTP APIを記述するための正式な標準だと説明しているよ。
一方でSwagger公式は、Swagger UI・Swagger Editor・Swagger Codegenなど、OpenAPI定義を扱うツール群を提供している。

そういう場面が多いね。
昔の名残で「Swagger」と呼ばれることもあるけど、仕様としてはOpenAPIと言う方が正確なことが多い。

いつもみたいに、レストランで例えてみようか。

APIは、レストランの注文窓口みたいなもの。
でも、お客さんが注文するにはメニューが必要だよね。

メニューに書いてあること
・注文できる料理
・値段
・サイズ
・トッピング
・注文方法
・提供される内容

そう。
SwaggerはAPIのメニュー表みたいなもの。

Swaggerに書いてあること

・使えるAPIのURL
・GET / POST などの方法
・送るパラメータ
・返ってくるデータ
・エラー時の返事

そう。
しかもSwagger UIなら、そのメニュー表から実際に注文、つまりAPIの実行を試せることがあるんだ。

Swagger UIは、API仕様書をブラウザで見やすく表示するツールだよ。

そう。
たとえば、こんな感じで表示される。

GET /users
ユーザー一覧を取得するAPI

POST /users
ユーザーを登録するAPI

GET /users/{id}
指定したユーザーを取得するAPI

そう。
さらに「Try it out」みたいな機能で、画面上からAPIを試せることもある。Swagger UIは、OpenAPI定義からインタラクティブなAPIドキュメントを生成するHTML・JavaScript・CSSのツールとして説明されているよ。

Swagger Editorは、API仕様を書くためのエディタだよ。

そう。
左側にOpenAPI形式の定義を書いて、右側に見た目のプレビューが出るようなイメージ。

左：YAMLやJSONでAPI仕様を書く
右：Swagger UIっぽい画面で確認する

そう。
API仕様書を書く練習にも便利だね。

Swagger Codegenは、OpenAPI定義をもとに、APIクライアントやサーバー側のひな形を自動生成するツールだよ。公式リポジトリでも、OpenAPI / Swagger定義を解析して、ドキュメント、APIクライアント、サーバースタブを生成するテンプレートエンジンとして説明されている。

そう。
たとえばAPI仕様がきちんと書かれていれば、

JavaScript用のAPI呼び出しコード
Java用のクライアントコード
サーバー側のひな形

みたいなものを作れる場合がある。

似たツールとして OpenAPI Generator っていうのもあるよ。
どちらもOpenAPI定義からクライアントコードやサーバーのひな形を生成する用途で使われるんだ。
初心者のうちは「仕様書からコードのひな形を作る道具がある」くらいで大丈夫だよ。

Swaggerには、APIを使う人が迷わないように「入口・送り方・返ってくる内容」を書くよ。

表にして一覧にするとこんな感じ。

そう。
OpenAPI仕様は、HTTP APIを標準的・言語非依存に記述し、人間とコンピュータの両方がAPIの能力を理解できるようにするものと説明されているよ。

すごく簡略化すると、こんな感じ。

YAMLやJSONで書くことが多いね。
これをSwagger UIで表示すると、見やすいAPIドキュメントになる。

Swaggerを使うと、API仕様を共有しやすくなるよ。
主なメリットはこんな感じ。

そうだね。

API仕様があいまいだと、フロント側は「この項目が返ると思ってた」、バックエンド側は「そんな仕様だと思ってなかった」みたいなズレが起きるよ。
Swaggerを使うと、そのズレを減らしやすくなるね。

逆に注意点はこんな感じ。

そう。
Swaggerは便利だけど、実装と仕様書を合わせ続けることが大事。

いろんな人が使うよ。

そう。
特にSwagger UIは、コードを読まなくてもAPIの全体像を見やすいからね。

違うけど、関係はあるね。

そう考えると分かりやすい。
ただし、Swagger UIでもAPIを試せるし、PostmanでもAPIドキュメントを扱えるから、役割が一部重なるところもある。

基本的には違う。
SwaggerはAPIそのものではなく、APIの仕様を説明したり、扱いやすくしたりするものだよ。

そう。
ただし、コード生成やモックサーバーと組み合わせると、開発を助けることはできる。

そこも注意。
コード生成でひな形は作れるけど、実際の処理や業務ロジックは別に実装する必要がある。

完全に切り離すより、歴史的につながっていると考えるといい。
今は仕様の名前としてはOpenAPI、ツール群や通称としてSwaggerが使われることが多い。

Swaggerとは、
APIの仕様書を作成・表示・共有・テストしやすくするためのツール群だよ。

そのとおり。
一言でまとめるなら、

Swaggerは、APIの説明書を作って、見て、試せるようにする道具

だね。