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本の定義ファイルから次のものを生成・検査できる点にあります。

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

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

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

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

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

寄贈後、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対応の現況にまとめています。

オープン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の併存設計で扱っています。

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

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

混同しやすいのが 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/[email protected] lint openapi.yaml

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

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

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

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

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点を挙げています。

先ほどの例の 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の実装を参照してください。

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

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

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

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

見送るかどうか迷う場合は、フレームワークの自動生成から始める方法もあります。FastAPIは型ヒントからOpenAPI定義を出力し（FastAPIのSwagger UI（/docs）自動生成）、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対応の現況
• OpenAPI Generatorとは｜生成できるもの・仕組み・対応言語と導入方法
• スキーマファーストとは？OpenAPI起点の並行開発と破壊的変更検知を解説
• API設計書の書き方｜記載項目チェックリストとOpenAPIサンプル・レビュー観点
• AsyncAPIとは？OpenAPIとの違いと3.0仕様・イベント駆動APIの設計を実装目線で解説