---
title: "OpenAPIとは？Swaggerとの違いと仕様書(YAML/JSON)の書き方｜3.0・3.1・3.2の差分"
url: "https://www.issoh.co.jp/tech/details/10408/"
published: 2025-12-26
updated: 2026-09-27
categories: ["API"]
publisher: "株式会社一創"
---

# OpenAPIとは？Swaggerとの違いと仕様書(YAML/JSON)の書き方｜3.0・3.1・3.2の差分

OpenAPIは、HTTP APIのエンドポイント・パラメータ・レスポンス・認証方式を、YAMLかJSONで機械可読に記述するための標準仕様です。正式名称はOpenAPI Specification（OAS）で、Linux Foundation配下のOpenAPI Initiative（OAI）が管理しています。Swaggerはこの仕様の旧称で、現在はSmartBear社のツール群の名前として残っています。この記事では、Swaggerとの違いを改称の経緯から整理したうえで、仕様書の構造、最小構成のYAMLの書き方とlintでの検証、3.0・3.1・3.2の差分、版を上げるときにつまずく箇所を説明します。

## まとめ：OpenAPIの定義とSwaggerとの違い、書き始める版の結論

- OpenAPIは「HTTP APIの外形（どのURLに何を送ると何が返るか）」を記述する仕様です。実装コードでもツールでもありません。
- Swagger 2.0までは仕様名がSwaggerでした。2015年にSmartBear社がOAIへ寄贈した後は2.0も「OpenAPI Specification 2.0」と呼ばれ、OAIが新たに策定した最初の版が3.0（2017年7月）です。現在「Swagger」と言えば、Swagger UI・Swagger Editor・Swagger Codegenなどのツールを指します。
- 銀行が外部事業者に口座情報などを提供する「オープンAPI」や、ChatGPTのOpenAI APIとは別物です。
- 仕様書のルートには `openapi`（版番号）と `info` が必須で、`paths`・`components`・`webhooks` のいずれか1つ以上を置きます。
- 最新版は3.2.1（2026年9月10日）です。新規に書くなら、使うツールがすべて対応している最も新しい版を選びます。3.0から3.1へ上げるときは、`nullable`・`exclusiveMinimum`／`exclusiveMaximum`・スキーマの `example`・ファイルアップロードの記述の4点を書き換えます。

## OpenAPIが定義するもの：HTTP APIの契約を機械可読にする仕様

仕様書の冒頭では、OASの目的を「ソースコードや追加の文書、通信の傍受に頼らずに、人とコンピューターの双方がサービスの機能を発見し理解できるようにする、プログラミング言語に依存しないHTTP APIのインターフェース記述」と定めています。記述対象はあくまでAPIの外形で、サーバーの内部処理やデータベース設計は書きません。

この仕様に従って書いたファイルを、仕様書ではOpenAPI Description（OAD）と呼びます。日本語の現場では「OpenAPI定義」「OpenAPI仕様書」「swagger.yaml」などと呼ばれますが、指しているものは同じです。

機械可読であることの利点は、1本の定義ファイルから次のものを生成・検査できる点にあります。

| 用途        | 代表的なツール                   | 定義ファイルから得られるもの    |
| --------- | ------------------------- | ----------------- |
| APIリファレンス | Swagger UI・Redoc          | ブラウザで試せるドキュメント    |
| コード生成     | OpenAPI Generator         | クライアントSDK・サーバーの雛形 |
| モックサーバー   | Prism                     | 実装前に叩けるダミーAPI     |
| lint・検証   | Redocly CLI・Spectral      | 記述ミスや規約違反の検出      |
| テスト       | Schemathesis・jest-openapi | レスポンスが定義どおりかの検査   |

どの用途も「定義ファイルが実装と一致している」ことが前提です。定義が古いまま放置されると、生成したSDKもドキュメントも誤った内容になります。コード生成の仕組みは[OpenAPI Generatorとは｜生成できるもの・仕組み・対応言語と導入方法](/tech/details/3353/)で、テストへの組み込みは[JestとOpenAPIでAPIテストを自動化する方法](/tech/details/2273/)で扱っています。

## OpenAPIとSwaggerの違い：仕様名とツールブランドの分離

OpenAPIとSwaggerの違いは、「仕様の名前」と「ツールの名前」の違いです。2015年までは仕様もツールもSwaggerと呼ばれていたため、古い資料では両者が混在しています。

### Swaggerの誕生からOpenAPI 3.0.0までの年表（2010〜2017年）

OAS 3.2.1の改訂履歴（Appendix A）と、OAI・Linux Foundationの公表資料に記載された日付を並べると、次のとおりです。

| 時期          | できごと                                         |
| ----------- | -------------------------------------------- |
| 2010年       | Wordnik社がSwagger仕様を作成                        |
| 2011年8月10日  | Swagger Specification 1.0 公開                 |
| 2014年9月8日   | Swagger 2.0 公開                               |
| 2015年3月     | SmartBear社がSwaggerプロジェクトを取得                  |
| 2015年11月5日  | SmartBear・Google・IBM・Microsoftなど10社でOAI設立を発表 |
| 2015年12月31日 | Swagger 2.0をOAIへ寄贈                           |
| 2016年       | 仕様がOAI管理の独立プロジェクトになる                         |
| 2017年7月26日  | OpenAPI 3.0.0 公開（OAIが策定した最初の版）               |

寄贈後、2.0の仕様書も「OpenAPI Specification Version 2.0」と改題されたため、「Swagger 2.0」と「OpenAPI 2.0」は同じ版を指します。2.0の定義ファイルは先頭行が `swagger: "2.0"`、3.0以降は `openapi: 3.0.4` のように書き出しのフィールド名自体が違います。手元のファイルがどちらの系統かは、この1行で判別できます。

### いま「Swagger」が指すものと、swaggerの語の意味

現在のSwaggerは、SmartBear社が提供するOpenAPI向けツール群のブランド名です。定義を画面に描くSwagger UI、書きながら検証するSwagger Editor、コードを生成するSwagger Codegenがオープンソースで、設計・ドキュメント公開の商用サービスも同じブランドで展開されています。英単語のswaggerは「自信たっぷりに振る舞う」という意味で、読み方は「スワッガー」です。

したがって「Swaggerで仕様書を書く」は、正確には「OpenAPIの仕様に従って書いたファイルを、Swaggerのツールで編集・表示する」という意味になります。Swagger UIとEditorをDockerで立てる手順や、3.2への対応状況は[Swaggerとは：Editor・UIをDockerで動かす手順とOpenAPI 3.2対応の現況](/tech/details/17451/)にまとめています。

## オープンAPI・OpenAI APIとの違い：同じ読みの別物を切り分ける

「OpenAPI」で検索すると、仕様とは無関係の2つの言葉が混ざります。

- **オープンAPI（銀行API）**：全国銀行協会は、APIの接続仕様を他の企業等に公開することを「オープンAPI」と呼ぶと説明しています。銀行の文脈では、金融審議会の報告にある「銀行がFintech企業等にAPIを提供し、顧客の同意に基づいて、銀行システムへのアクセスを許諾すること」を指し、口座情報や入出金明細の照会、振込の指示などが対象です。2017年の銀行法改正では、こうしたAPIに接続する事業者向けに電子決済等代行業の登録制度が設けられました（2018年6月施行）。仕様の名前ではなく、APIを外部に開放する取り組みの呼び名です。
- **OpenAI API**：ChatGPTを提供するOpenAI社の、生成AIモデルを呼び出すためのAPIです。綴りが1文字違うだけで、OpenAPI仕様とは関係がありません。

銀行のオープンAPIの中身をOpenAPI仕様で記述することは可能ですが、両者は「施策」と「記述形式」という別の層の言葉です。金融機関との接続方式は[金融のデータ連携｜行内3層と対外3経路の切り分け・電文とAPIの併存設計](/column/details/16928/)で扱っています。

## 仕様書の基本構造：openapi・info・pathsなどルート要素の役割

OAS 3.2.1では、ルートのOpenAPI Objectに `openapi` と `info` が必須で、加えて `components`・`paths`・`webhooks` のうち少なくとも1つを置くよう定めています。3.0までは `paths` 自体が必須でしたが、3.1からは部品だけを集めた定義ファイルも書けるようになりました。

| フィールド      | 必須     | 書く内容              |
| ---------- | ------ | ----------------- |
| openapi    | 必須     | 準拠する仕様の版（例 3.1.2） |
| info       | 必須     | APIの名前・版・ライセンス    |
| servers    | 任意     | 接続先のURL           |
| paths      | いずれか1つ | エンドポイントと操作        |
| components | いずれか1つ | 再利用するスキーマ・パラメータ   |
| webhooks   | いずれか1つ | API側から送る通知（3.1〜）  |
| security   | 任意     | 全体に適用する認証方式       |
| tags       | 任意     | 操作の分類             |

混同しやすいのが `openapi` と `info.version` です。前者は仕様の版、後者は自分のAPIの版で、仕様書にも「info.versionとは無関係」と明記されています。

### YAMLとJSONの選び分け：YAML 1.2推奨と入口ファイル名

どちらで書いても表現できる内容は同じで、相互に変換できます。仕様書は入口となるファイル名を `openapi.yaml` または `openapi.json` にすることを推奨し、YAMLを使う場合はYAML 1.2を推奨しています。人が手で書くならコメントを残せて差分も読みやすいYAML、プログラムで生成・加工するならJSONが扱いやすいという使い分けが目安です。

## OpenAPI仕様書の書き方：最小構成のYAMLを書いてlintで検証する

Todoを1件取得するAPIを、3.1系の最新パッチであるOAS 3.1.2で書いた例です。Redocly CLI 2.54.3の既定ルールセット（recommended）でlintし、エラーも警告も出ないことを確認しています。

```
openapi: 3.1.2
info:
  title: Todo API
  version: 1.0.0
  license:
    name: MIT
    identifier: MIT
servers:
  - url: /v1
security: []
paths:
  /todos/{id}:
    get:
      summary: Todoを1件取得する
      operationId: getTodo
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 取得成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Todo'
        '404':
          description: 該当なし
components:
  schemas:
    Todo:
      type: object
      required: [id, title]
      properties:
        id:
          type: integer
        title:
          type: string
        dueDate:
          type: [string, 'null']
          format: date
```

`paths` の下にURL、その下にHTTPメソッドを書きます。`{id}` のようなパスパラメータは `in: path` と `required: true` を必ず付けます。レスポンスの形は `components.schemas` に1回だけ定義し、`$ref` で参照します。

lintはNode.jsがあれば、事前のインストールなしでnpx経由で実行できます（初回はパッケージの取得を確認されます）。

```
npx @redocly/cli@2.54.3 lint openapi.yaml
```

既定ルールは記述ミスだけでなく運用上の推奨も検査します。上の例から `servers`・`summary`・`security` を削ると、仕様としては正しくても、それぞれ no-empty-servers・operation-summary・security-defined の各ルールでエラーになりました。`security: []` は「ルートで要求する認証方式は無い」と明示する書き方で、security-defined ルールはこれを定義済みとして扱います。

チームで書き始める前に、記載項目やレビュー観点を揃えておきたい場合は[API設計書の書き方｜記載項目チェックリストとOpenAPIサンプル・レビュー観点](/tech/details/4068/)が参考になります。

## 3.0・3.1・3.2の違い：新規定義で選ぶ版の基準

OASは「メジャー.マイナー.パッチ」で版を付け、3.1のようなメジャー.マイナーの部分が機能セットを表します。パッチ版は誤記の修正や説明の明確化だけで、機能は増えません。3.1対応をうたうツールは3.1.xのすべてに対応すべきとされています。

| 版   | 初版公開       | 最新パッチ             | 主な変更                           |
| --- | ---------- | ----------------- | ------------------------------ |
| 3.0 | 2017-07-26 | 3.0.4（2024-10-24） | Swagger 2.0からの全面改訂             |
| 3.1 | 2021-02-15 | 3.1.2（2025-09-19） | JSON Schema 2020-12準拠・webhooks |
| 3.2 | 2025-09-19 | 3.2.1（2026-09-10） | タグ階層・QUERY・ストリーミング             |

### 3.1の変更：スキーマがJSON Schema 2020-12と揃った

3.0のSchema Objectは「JSON Schema Wright Draft 00の拡張サブセット」で、nullを型として持てず、代わりに独自の `nullable` を使っていました。3.1ではSchema Objectが「JSON Schema Draft 2020-12のスーパーセット」になり、null許容は `type: [string, 'null']` のように型の配列で書きます。あわせて `webhooks`、`info.summary`、ライセンスをSPDX識別子で書く `license.identifier` が加わりました。

### 3.2の追加：タグの階層化とQUERYメソッド、ストリーミング

3.2.0では、タグに親子関係を表す `parent` と種類を表す `kind` が加わり、ドキュメントのナビゲーションを階層で組めるようになりました。HTTPメソッドにはQUERYが加わり（3.2.0の時点ではIETFのドラフトを参照し、3.2.1で2026年6月発行のRFC 10008に差し替え）、それ以外の任意のメソッドは `additionalOperations` に書けます。ほかに、クエリ文字列全体を1つの値として扱う `in: querystring`、SSEのような連続データの各要素を定義する `itemSchema`、文書自身のURIを宣言する `$self`、OAuth 2.0のデバイス認可フロー（`deviceAuthorization`）が追加されています。

新規の定義は、読み込ませるツール（ドキュメント表示・コード生成・lint・ゲートウェイ）のすべてが対応している最も新しい版で書くのが原則です。上の例のヘッダーを `openapi: 3.2.0` に変えてもRedocly CLI 2.54.3のlintは通りましたが、コード生成やAPIゲートウェイは対応が遅れることがあります。3.2の新機能を使わないなら3.1で書いておき、ツールの対応を確認してから上げても失うものはありません。

## 3.0の書き方を3.1に持ち込む失敗：nullableとexclusiveMinimum

版を上げるときは、先頭の `openapi: 3.0.4` を `3.1.2` に書き換えるだけでは済みません。OAIの移行ガイドは、スキーマの必須の書き換えとして次の4点を挙げています。

| 項目            | 3.0の書き方                             | 3.1以降の書き方                |
| ------------- | ----------------------------------- | ------------------------ |
| null許容        | type: string ＋ nullable: true       | type: \[string, ‘null’\] |
| 下限を含まない       | minimum: 0 ＋ exclusiveMinimum: true | exclusiveMinimum: 0      |
| スキーマの例        | example: fedora                     | examples: \[fedora\]     |
| Base64のアップロード | format: base64                      | contentEncoding: base64  |

先ほどの例の `dueDate` を3.0の書き方に戻し、ヘッダーは3.1.2のままでlintすると、Redocly CLIは `` Property `nullable` is not expected here. `` としてエラーを出しました。`exclusiveMinimum: true` も `` Expected type `number` but got `boolean`. `` で止まります。この2つはlintで気づけます。一方、スキーマ内の `example` はRedocly CLI 2.54.3のrecommendedでもエラーにならないため、残りの2点は移行ガイドと突き合わせて確認します。バイナリのアップロードは、3.1ではスキーマを書かずに `application/octet-stream: {}` とするのが移行ガイドの例です。

厄介なのは、lintを通さずにJSON Schema 2020-12の検証器へ渡した場合です。Pythonのjsonschema 4.25.1で `{"type": "string", "nullable": true}` に対してnullを検証すると、結果は不合格でした。2020-12は知らないキーワードを無視するため、`nullable` は黙って捨てられ、nullを許容するつもりのフィールドが実際には拒否されます。版を上げるコミットでは、定義ファイル全体を `nullable` と `exclusiveM`（exclusiveMinimum／exclusiveMaximumの両方に一致）で検索し、型の配列と数値に書き換えてからlintを通します。

JSON Schema側の書き方を詳しく確認したい場合は[JSON Schemaとは？JSONの構造を検証する書き方とDraft 2020-12の実装](/tech/details/16289/)を参照してください。

## OpenAPIを採用する場面と見送る場面

OpenAPIが効果を出すのは、APIの提供側と利用側が別のチームや別の会社に分かれている場合です。フロントエンドとバックエンドを並行して開発する、外部にAPIを公開する、複数言語のSDKを配る――こうした場面では、定義ファイルが両者の契約になり、モックやSDKを先に配れます。定義を先に書いてから実装する進め方は[スキーマファーストとは？OpenAPI起点の並行開発と破壊的変更検知を解説](/tech/details/16302/)で、仕様書を起点にAIエージェントに実装させる開発手法は[仕様駆動開発（SDD／Spec-Driven Development）とは](/tech/details/8740/)で説明しています。

一方、次の場面ではOpenAPIを主軸にしません。

- GraphQLやgRPCのAPI：それぞれSDL・Protocol Buffersという専用の定義形式があり、そちらが正本になります。
- メッセージキューやWebSocket中心のイベント駆動API：非同期の送受信は[AsyncAPIとは？OpenAPIとの違いと3.0仕様](/tech/details/13797/)で記述します。
- 利用者が同じリポジトリ内の1画面だけで、仕様変更も同じ人が同時に行う小さな内部API：定義ファイルを保守する手間が、得られる契約の効果を上回ります。

見送るかどうか迷う場合は、フレームワークの自動生成から始める方法もあります。FastAPIは型ヒントからOpenAPI定義を出力し（[FastAPIのSwagger UI（/docs）自動生成](/tech/details/2246/)）、Spring Bootではspringdoc-openapiが同じ役割を担います。この場合は実装が正本になるため、定義ファイルを手で書き換えないよう運用を決めておきます。

## よくある質問

### OpenAPIとSwaggerの違いを一言でいうと何ですか？

OpenAPIは仕様の名前、Swaggerはその仕様を扱うツール群の名前です。Swagger 2.0までは仕様もSwaggerと呼ばれていましたが、2015年の寄贈後は2.0も「OpenAPI 2.0」と呼ばれ、3.0以降はOpenAPIの名前で策定されています。

### OpenAPIの最新バージョンはいくつですか？

2026年9月26日時点の最新版は、2026年9月10日公開の3.2.1です。3.2.1はパッチ版のため、機能は2025年9月19日公開の3.2.0と同じです。

### swagger: “2.0” の古い定義ファイルは今も使えますか？

多くのツールは2.0も読み込めますが、3.x系とは構造が異なり、3.1以降のwebhooksやJSON Schema準拠のスキーマは使えません。保守を続けるなら、変換ツールで3.xへ移し、lintを通してから運用するのが安全です。

### OpenAPIの利用にライセンス料はかかりますか？

かかりません。仕様書そのものがApache License 2.0で公開されており、仕様に従って定義ファイルを書くことにも、オープンソースのツールで扱うことにも費用は発生しません。有償なのは一部の商用ツールやホスティングサービスです。

### OpenAPIとAPI仕様書は同じものですか？

OpenAPIで書いた定義ファイルはAPI仕様書の一種ですが、API仕様書のすべてではありません。業務上の制約、レート制限の運用、エラー時の問い合わせ手順などは、OpenAPIの外に書く必要があります。

## 関連記事

- [Swaggerとは：Editor・UIをDockerで動かす手順とOpenAPI 3.2対応の現況](/tech/details/17451/)
- [OpenAPI Generatorとは｜生成できるもの・仕組み・対応言語と導入方法](/tech/details/3353/)
- [スキーマファーストとは？OpenAPI起点の並行開発と破壊的変更検知を解説](/tech/details/16302/)
- [API設計書の書き方｜記載項目チェックリストとOpenAPIサンプル・レビュー観点](/tech/details/4068/)
- [AsyncAPIとは？OpenAPIとの違いと3.0仕様・イベント駆動APIの設計を実装目線で解説](/tech/details/13797/)

---

出典: [OpenAPIとは？Swaggerとの違いと仕様書(YAML/JSON)の書き方｜3.0・3.1・3.2の差分](<https://www.issoh.co.jp/tech/details/10408/>)（株式会社一創）