1. はじめに

最近業務で触れる機会がある「Swagger」について、検索すると仕様の話とツールの話が混ざって出てくるなあと思っています。

Swagger 2.0がOpenAPI 3.0になった、と書いてある記事
Swaggerはツールの名前だ、と書いてある記事
SwaggerでAPIドキュメントを作る、というタイトルの記事

どれも間違っているわけではないと思っており、初見だと「で、Swaggerって何なの」となります。私がそうでした。

この記事では、実際にYAMLを書く話には踏み込まず、まずは名前の整理だけをしてみようと思います。

✅ SwaggerとOpenAPIは何が違うのか
✅ なぜ名前が2つあるのか
✅ Swagger UI / Editor / Codegen はそれぞれ何をするものか
✅ 2.0と3.0の見分け方（コピペしたYAMLが動かない原因）

想定読者

Swaggerという言葉は聞くけど、何を指しているのか自信がない方
先輩に「Swaggerで書いといて」と言われて、何をすればいいのか分からなかった方

2. 結論：仕様とツールで名前が違う

呼び名	実体
OpenAPI（OpenAPI Specification / OAS）	APIの仕様を書くためのフォーマットの規格
Swagger	SmartBear社が作っているツール群の名前

OpenAPI … 書き方のルール（YAMLやJSONでこう書きます、という決まりごと）
Swagger … そのルールで書かれたファイルを読み込んで、いい感じに表示したりコードを生成したりするツール

「SwaggerでAPI仕様書を書く」という言い方をよく見ますが、厳密にはOpenAPIの形式で書いて、Swaggerのツールで見ていることになります。

ここだけ押さえておけば、大体の記事は読めるようになると思いました。

3. なぜ名前が2つあるのか

そもそも昔は仕様自体の名前がSwaggerだったそうです。
ざっくりとした流れはこうなっています。

時期	出来事
2011年	Tony Tam氏がSwaggerを公開。当時は仕様もツールもSwaggerだった
2014年9月	Swagger 2.0 リリース
2015年11月	SmartBearが、仕様をLinux Foundation傘下のOpenAPI Initiativeに寄贈すると発表
2016年1月1日	仕様の名前が OpenAPI Specification（OAS）に変更
2017年7月	OAS 3.0.0 リリース
2021年2月	OAS 3.1.0 リリース
2025年9月	OAS 3.2.0 リリース

ポイントは、2016年の改称と2017年の3.0リリースは別の出来事というところにあるようです。

2016年の改称 … 名前が変わっただけで、中身は同じ。Swagger 2.0 と OpenAPI 2.0 は同一のもの
2017年の3.0 … こちらは仕様そのものの改訂。書き方がそこそこ変わった

「Swagger 2.0がOpenAPI 3.0に改名された」という説明を見かけることがあったのですが、これだと2つの出来事が1つにまとまってしまっています。

改称と改訂が別々にあった、と分けて覚えたほうが混乱しないと思います。

そして仕様が手を離れたあとも、SmartBearはツールをSwaggerブランドのまま作り続けているそうです。これが今の「仕様=OpenAPI、ツール=Swagger」という状態です。

4. Swaggerと名前が付くツールたち

「Swagger」と付くものが複数あるので、それぞれ何をするのか整理してみます。

Swagger UI

OpenAPIのファイルを読み込んで、ブラウザで見られるドキュメントに変換するツールです。エンドポイントの一覧、パラメータ、レスポンスの例が表示されます。

「Try it out」ボタンから実際にリクエストを投げられるのも特徴だと思います。

ただし注意点として、Swagger UIに表示されている内容は、実際のAPIの挙動ではなくYAMLに書かれた内容です。定義と実装がズレていても、UI側は何も教えてくれないそうで。。ここは最初に勘違いしやすいところかなと思います。

Swagger Editor

ブラウザ上でOpenAPIのYAMLを書くためのエディタです。
左に書いて、右にSwagger UIのプレビューが出ます。

書式が間違っているとその場で指摘してくれるので、私は最初に触るならこれが分かりやすいなと思いました。editor.swagger.io で、インストールなしですぐ試すことができます。

Swagger Codegen

OpenAPIの定義から、クライアントやサーバのコードを生成するツールです。

なお2018年にこのプロジェクトから OpenAPI Generator というフォークが生まれていて、今はそちらのほうがよく使われている印象があります。Codegenを調べているとOpenAPI Generatorが出てくるのは、そういう経緯があるのかなと思っています。

SwaggerHub

上記をまとめたSaaSです。
チームでの共同編集やバージョン管理ができます。個人で試す段階では、使わなそうな印象を持ちました。

5. 2.0と3.0の見分け方

ネット上のサンプルは2.0系と3.0系が混在しています。コピペしたYAMLが動かないときは、大体このバージョンが原因だとおもっています。

見分け方は簡単で、ファイルの先頭を見ます。

swagger: "2.0"   # ← 2.0系

openapi: 3.0.3   # ← 3.0系

主な差分はこのあたりです。

やりたいこと	2.0	3.0
リクエストボディを定義する	`in: body` のパラメータ	`requestBody`
スキーマを共通化する	`definitions`	`components/schemas`
認証方式を定義する	`securityDefinitions`	`components/securitySchemes`
Content-Typeを指定する	`consumes` / `produces`	`content` 配下のメディアタイプ
APIのURLを指定する	`host` / `basePath` / `schemes`	`servers`

3.1以降もありますが、実務で見かけるのはまだ3.0系が多い印象です。
3.1はJSON Schemaとの互換性が上がったバージョンで、対応していないツールもあるので、最初は3.0で書いておけば困らないと思います。

6. 実物を見てみる

openapi: 3.0.3
info:
  title: ユーザーAPI
  version: 1.0.0
paths:
  /users/{userId}:
    get:
      summary: ユーザーを1件取得する
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ユーザー情報
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string }
                  name: { type: string }

やっていること：

openapi … どのバージョンの書き方で書いているか
info … APIの名前とバージョン
paths … どのURLに、どのHTTPメソッドがあるか
parameters … 何を渡せるか
responses … 何が返ってくるか

上記を editor.swagger.io に貼り付けると、右側にドキュメントが表示されます。手を動かすと一気に理解が進みました！

7. まとめ

呼び名	実体
OpenAPI	APIの仕様を書くためのフォーマットの規格
Swagger	その規格を扱うSmartBear社のツール群

覚えておくと迷いにくいポイントは3つです。

昔は仕様自体がSwaggerという名前だった。2016年にOpenAPIへ改称
改称（2016年）と3.0のリリース（2017年）は別の出来事
ファイル先頭の swagger: / openapi: でバージョンが分かる

名前の整理がついたので、次回の記事では実際に書いてみようと思います。
この記事が少しでも参考になりましたら、いいね／ストックをしてもらえるととっても励みになります！

参考資料

OpenAPI Initiative
https://www.openapis.org/
OpenAPI Specification（最新版）
https://spec.openapis.org/
Swagger 公式
https://swagger.io/