Swagger は、OpenAPI形式のAPI仕様書を扱うツール群の名前として使われることが多い言葉です。
代表的には、API仕様書をブラウザで見やすく表示する Swagger UI、YAMLを書きながら確認できる Swagger Editor、コード生成に使う Swagger Codegen などがあります。
まず押さえたいポイント
- 現在の仕様名としては OpenAPI が使われる
- Swaggerはツール名や旧称として現場に残っていることが多い
Swaggerを見るは、Swagger UIで表示されたAPIドキュメントを見る意味で使われやすい- 中身の定義ファイルはOpenAPI形式であることが多い
OpenAPIとの違い
ざっくり言うと、OpenAPIは仕様、Swaggerはその仕様を扱うツール群です。
ただし、昔からの呼び方として Swagger仕様書 Swagger定義 と言われることもあります。
会話では意味が通じることも多いですが、設計資料やリポジトリでは OpenAPI仕様書 と書いた方が、仕様とツールを分けて理解しやすくなります。
どんな場面で見るか
Swagger UIは、APIの使い方をブラウザで確認するときによく使われます。
エンドポイント一覧、パラメータ、リクエストボディ、レスポンス例、ステータスコードなどを画面で確認できるため、API利用者にとって入口になりやすいです。
Swagger Editorは、OpenAPIのYAMLやJSONを書きながら表示を確認する用途で使われます。
Swagger Codegenのようなツールは、OpenAPI仕様書からクライアントSDKやサーバーのひな形を作る用途で使われます。
注意点
Swaggerがあるから安心 とは限りません。
表示されている内容が古い、エラー形式が書かれていない、認証の説明が足りない、実際のAPIレスポンスと型が違う、といった状態では、見た目が整っていても仕様書としては危険です。
また、Swaggerという名前だけで会話すると、ツールの話なのか、OpenAPI定義ファイルの話なのか、ブラウザ上のAPIドキュメントの話なのかが混ざることがあります。
チーム内では OpenAPI定義 Swagger UI 生成コード のように分けて呼ぶと、認識違いを減らせます。
SwaggerとOpenAPIの関係、API仕様書をチームで共有する考え方は、OpenAPI / Swaggerとは？API仕様書をチームで共有する基本を整理 で詳しく整理しています。