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/