OpenAPIとは｜Swaggerとの違い・仕様書の書き方と運用

OpenAPIとは｜Swaggerとの違いと基本概念

OpenAPIを使うと、1つの仕様書からAPIドキュメント・SDK・モックサーバを生成できます。記述の対象は、エンドポイント・パラメータ・リクエストとレスポンスの形・認証方式で、YAMLまたはJSONで書きます。人間が読む文書であると同時に、ツールが解釈して処理できる点が普通の設計書と違います。

仕様そのものを指す言葉である

OpenAPIが定めているのは「何をどう書くか」だけです。書いた結果をどう使うかは各ツールに委ねられています。だからこそ、同じ1本のファイルからドキュメントもクライアントSDKもモックサーバも出てきます。

公式の入門サイトでは、この記述のまとまりをOpenAPI Description（OAD）と呼びます。「特定バージョンのOpenAPI Specificationに従って書かれた1つ以上のドキュメントで、まとめて1つのAPIを記述するもの」という定義です（OpenAPI Initiative 用語集）。ファイルが複数に分かれていても、論理的には1つのOADとして扱います。この区別を知っていると、後述するファイル分割の話が理解しやすくなります。

Swaggerとの違いと、名前が混ざる理由

Swaggerは2011年に登場した先行プロジェクトの名前でした。2015年にSmartBear Softwareが仕様をOpenAPI Initiativeへ寄贈し、2016年からLinux Foundation傘下の独立プロジェクトになっています（OpenAPI Initiative FAQ）。

つまり仕様を指すなら「OpenAPI」、ツールを指すなら「Swagger」が正確です。ただし現場では3.x系の仕様書を指して「Swagger書いといて」と言われるケースが今も普通にあります。指摘して回るより、どちらの意味で使われているか確認するほうが早いでしょう。

ミニFAQ：Swagger 2.0のまま運用している案件は移行すべき？

すぐに移行しなければ壊れるものではありません。ただし新しいツールは3.x系のみ対応が増えており、2.0のままだとコード生成やLintの選択肢が狭まります。既存の2.0ファイルは変換ツールで3.0へ機械変換できるため、移行判断はツールの必要性から逆算すると決めやすくなります。

バージョンの違いと選び方

結論として、新規案件は3.1系以降、既存が3.0系なら急いで上げる必要はないという整理になります。判断材料は、使いたいツールが対応しているかどうかに集約されます。

公式のリビジョン履歴（OpenAPI Specification 3.2.1 付録A）によると、主要な版のリリース時期は次のとおりです。

最新版の確認は公式の版一覧ページで行えます。バージョンは年単位で動くため、着手時に一度見ておくと安全です。

3.0から3.1で変わったこと

3.1の最大の変更は、JSON Schema Draft 2020-12と完全互換になった点です。3.0までは「JSON Schemaに似た独自サブセット」だったため、スキーマ関連のツールがそのまま使えない場面がありました。

実務で影響が出るのは次の4つです（3.0から3.1への移行ガイド）。

• nullable: true が廃止され、型を配列で書く形（stringとnullを並べる）に変わった

• exclusiveMinimum／exclusiveMaximum が真偽値から数値そのものに変わった

• Schema Object内のサンプル表現がJSON Schema準拠になり、examples を使う場面が出てきた

• JSON Schema互換の影響で、バイナリ表現やエンコード関連（format: binary の扱い）の記述方法を見直す場面がある

既存の3.0ファイルを3.1へ上げるときは、このnullableの書き換え漏れが一番よく残ります。

3.2で追加されたもの

3.2は3.1に対する破壊的変更を含みません。仕様上は既存文書を大きく書き換えずに移行しやすい一方で、実際には利用中のツールが3.2を解釈できるかの確認が必要です。追加されたのは主に、これまで書けなかったものを書けるようにする拡張です（3.1から3.2への移行ガイド）。

• タグの階層化（親子関係と分類を付けられる）

• SSEやJSON Linesのような逐次・ストリーミング応答の記述

• HTTPのqueryメソッド対応と、標準外メソッドの記述手段

• OAuth2デバイス認可フローへの対応

• ドキュメント自身のベースURIを宣言する仕組み

ストリーミング応答を扱うAPIは3.1までは記述が苦しく、説明を description に書き下すしかありませんでした。LLM関連のAPIを扱う案件ではここが効いてきます。

API仕様書の書き方｜基本構造

OpenAPIのファイルは、トップレベルに数個の要素を置き、その下に詳細をぶら下げる構造です。最初に全体像を押さえると迷いにくくなります。

pathsの下はパス、メソッド、応答の順に入れ子にする

paths の下にURLパスを書き、その下にHTTPメソッド、さらにその下にパラメータとレスポンスを書きます。レスポンスはステータスコードごとに、content の下でメディアタイプ別にスキーマを持たせる形です。

慣れるまで戸惑うのは、同じ「パラメータ」でも置き場所が分かれる点でしょう。パスパラメータとクエリパラメータは parameters に書きますが、リクエストボディは requestBody という別の要素になります。3.0で分離された仕様です。

componentsと$refで重複を減らす

同じスキーマを何度も書くと、変更時に必ず食い違いが出ます。共通部分は components の下に定義し、使う場所から $ref で参照します。

公式のベストプラクティスでも、DRY原則に従って共通部をcomponentsへ寄せることが推奨されています（OpenAPI Initiative Best Practices）。エラーレスポンス、ページネーションのメタ情報、IDの型あたりは早い段階で切り出しておくと後が楽になります。

参照は同一ファイル内だけでなく、別ファイルや外部URLも指定できます。規模が大きくなったらファイルを分割し、配信時にバンドルして1枚に戻す運用が一般的です。

exampleとexamplesは併用できない

細かいですが事故が多い箇所です。1つのオブジェクトの中でexample と examples の両方を書くことはできません。examples は名前をキーにしたマップで、それぞれに summary や description を付けられます（ドキュメント記述の指針）。

複数パターンを見せたいときは examples、1つで足りるなら example と覚えておけば足ります。注意したいのは、ParameterやMedia Type側の example／examples と、Schema Object側の examples は文脈が別物だという点です。前者はOpenAPI独自のサンプル指定、後者は3.1以降でJSON Schemaに準拠した配列形式で、同じ名前でも書き方が違います。ここを混同すると、生成物にサンプルが出ない事故につながります。

認証はsecuritySchemesで定義して参照する

認証方式は components の securitySchemes に定義し、security で適用します。APIキー、HTTP認証、OAuth2、OpenID Connectが書けます（セキュリティの記述）。

全体に適用したうえで、公開エンドポイントだけ個別に空の security で上書きする書き方が実務ではよく使われます。

ミニFAQ：oneOfとallOfはどう使い分ける？

複数の型のいずれか1つに一致させたいときが oneOf、複数のスキーマをすべて満たす合成が allOf です。継承のような表現をしたい場合は allOf で共通部を取り込み、判別が必要なら discriminator を添えます。anyOf は「1つ以上に一致」なので、判定を緩くしたいとき以外は oneOf のほうが意図が明確になります。

design-firstとcode-firstの使い分け

先に仕様を書くのがdesign-first、実装から仕様を生成するのがcode-firstです。公式にはdesign-first寄りの考え方が示されています。OpenAPIがあらゆるHTTP APIを記述できるわけではなく限界があるため、後付けで書くと直感的でない・不完全な記述になりやすい、という理由です（Best Practices）。ただし実務では、体制や既存資産の都合でcode-firstが合理的な場面もあります。

実際の判断は、体制で決まる部分が大きいところです。

code-firstを選ぶ場合でも、生成物をそのまま納品物にはしないほうが無難です。自動生成された記述は説明が薄く、利用側が読んでも使い方がわからないケースが多くなります。FastAPIのように型情報から自動生成できるフレームワークでも、説明とサンプルは手で足す前提で考えておくとよいでしょう。

コード生成・モック・ドキュメントのツール

OpenAPIの投資対効果は、1本のファイルから何を生やせるかで決まります。公式がツール一覧を公開しており、用途別に選べます。

TypeScript環境で型安全に寄せるなら、openapi-typescriptやorvalの組み合わせが扱いやすい部類です。周辺構成は「TypeScript開発環境2026｜Hono・Prisma・Zodで組むモダンスタック」でも触れています。

モックサーバの効き目が大きいのは、フロント側の待ち時間を消せる点です。仕様さえ合意できれば、バックエンドの実装完了を待たずにフロントの結合を進められます。マイクロサービス構成のようにチーム間の依存が多い現場ほど差が出ます。

仕様を腐らせない運用｜CIに載せる3点

ここが本記事の中心です。仕様書が使われなくなる原因はほぼ1つで、実装と乖離しても誰も気づかないことに尽きます。人の注意力ではなくCIで止めるのが現実的な解になります。

Lintで書き方を揃える

Spectralやvacuumで、記述ルールを機械的にチェックします。命名規則、descriptionの必須化、レスポンス定義の抜けなどをルール化しておくと、レビューで細かい指摘をする必要がなくなります。

導入の順序としては、まず既定ルールで走らせて警告の量を見てから、現場に合わないルールを落としていくほうが早く定着します。最初から独自ルールを作り込むと運用されません。

破壊的変更を差分で検出する

oasdiffを使うと、変更前後の2つの仕様を比較して破壊的変更を検出できます。必須パラメータの追加、レスポンスフィールドの削除、型の変更あたりが対象です。

プルリクエストで破壊的変更が出たらCIを落とす設定にしておくと、利用側に黙って壊す事故がなくなります。GitHub ActionsなどのCIに組み込むのが手軽でしょう。

分割とバンドルを自動化する

仕様が数千行を超えると1ファイルでは扱えません。パスやスキーマごとにファイルを分け、配信用に1枚へまとめる運用にします。Redocly CLIのようなツールがbundleとsplitの両方を持っています。

分割した状態をリポジトリの正とし、バンドル結果は成果物として生成する形が管理しやすい構成です。

実務で詰まりやすいポイントと参画直後チェックリスト

現場で繰り返し出てくる論点を先に挙げておきます。

1. nullableの移行漏れ：3.0から3.1へ上げたのにnullable記法が残っている。Lintで検出できます

2. $refの循環参照：AがBを参照しBがAを参照する構造。ツールによって挙動が割れるため避けます

3. exampleとexamplesの混在：同一オブジェクトでの併用は不可。生成物の例が消える原因になります

4. 相対参照の基準URIがずれる：ファイル分割時に発生しがち。3.2で導入されたベースURI宣言が効きます

5. 仕様と実装の二重管理：design-firstなのに実装側で勝手に増やす。差分検出をCIに入れて止めます

参画初日にやる仕様書の健全性チェック

このページ独自の整理として、参画直後に確認すべき項目をまとめます。所要時間は30分程度、遅くとも参画3日以内に済ませておくと後の手戻りが減ります。

乖離が見つかった場合、いきなり全体を直そうとしないほうがよいでしょう。自分が触る範囲だけを正しくして、差分検出をCIに入れる提案から始めるほうが通りやすくなります。この進め方は「フリーランス参画初月の立ち上がり方｜30日で信頼を得るオンボーディング型」の考え方とも重なります。

フリーランス案件でOpenAPIはどう評価されるか

OpenAPIそのものを対策KWにした募集は多くありません。単独スキルというより、API設計・バックエンド案件の中で前提として求められる位置づけです。公開案件の募集要件では「OpenAPIによるスキーマ駆動開発の経験」といった形で、他の要件と束ねて記載されるケースが見られます。

評価につながりやすいのは、書ける事そのものより運用を設計できることです。Lintルールの整備、破壊的変更の検知、複数チームへの仕様配布あたりまで経験があると、設計寄りのポジションで話が進みやすくなります。上流の評価軸については「エンジニアの設計力・上流スキルの磨き方｜段階別ロードマップと単価アップ」でも整理しています。

バックエンド領域全体の単価レンジを把握したい場合は「バックエンドフリーランスの単価相場｜言語別・レイヤー別レンジと動向」が参考になります。自分の経歴でどのあたりを狙えるか確認したい方は、無料のフリーランスエンジニア単価診断で市場単価の目安を出せます。実際の募集内容は案件一覧でも確認できます。

まとめ

OpenAPIは仕様のフォーマット、Swaggerはそれを扱うツール群の名前であり、価値が出るのは仕様書を書いた後の運用をCIに載せてからです。

要点を整理します。

• 新規に書くなら3.1系以降を選ぶ。3.1でJSON Schemaと完全互換になり、独自記法が消えた

• 執筆時点の最新は3.2.1（2026年9月10日付）。3.2は3.1に対する破壊的変更がなく移行しやすい

• 共通部はcomponentsへ寄せて$refで参照する。エラーレスポンスとIDの型は早めに切り出す

• design-firstが公式推奨だが、体制で判断してよい。code-firstでも説明とサンプルは手で足す

• Lint・破壊的変更の差分検出・バンドルの3点をCIへ載せると陳腐化が止まる

• 参画直後は仕様バージョン・最終更新・実装との乖離の3点を30分で確認する

次のステップとしては、手元のAPIを10本だけ書いてSwagger UIで表示し、Prismでモックを立てるところまでを一度通してみるのが早道です。ツールの選定手順そのものを整理したい場合は「技術選定の進め方5ステップ｜評価軸の作り方と提案を通す型」も合わせて確認してみてください。

参照した一次情報は次のとおりです。

• OpenAPI Specification 3.2.1（公式仕様）

• 公開されている仕様バージョン一覧

• OpenAPI Initiative 公式FAQ

• OpenAPI 入門・ベストプラクティス

• 3.0から3.1への移行ガイド

• 3.1から3.2への移行ガイド

• OpenAPI 公式ツール一覧