OpenAPI / Swaggerとは？API仕様書をチームで共有する基本を整理

先に要点

OpenAPIは、HTTP APIの仕様を機械にも人にも読める形で書くための標準仕様です。
Swaggerは、OpenAPI仕様書を表示・編集・コード生成などに使うツール群の名前として使われることが多いです。
API仕様書には、エンドポイント、HTTPメソッド、リクエスト、レスポンス、認証、エラー、サンプルを書くとチームで共有しやすくなります。
大事なのは、作ることより更新され続けることです。実装と仕様書がずれると、むしろ混乱の元になります。

APIを作っていると、このエンドポイントは何を受け取るのか このレスポンスの項目は必須なのか エラー時は何が返るのか がチーム内で曖昧になりがちです。
口頭やチャットで補足しているうちは何とかなっても、フロントエンド、バックエンド、QA、外部連携先が増えると、同じ認識を保つのが難しくなります。

そこで使われるのが OpenAPI です。
OpenAPIは、API の仕様をJSONやYAMLで書き、ドキュメント表示、モック、テスト、クライアントコード生成などにつなげやすくするための標準です。

この記事では、2026年4月22日時点で OpenAPI Specification v3.2.0、OpenAPI Initiative、Swagger公式情報を確認しながら、OpenAPI / Swaggerとは何か、API仕様書をチームで共有するときの基本を整理します。
REST APIそのものが曖昧な場合は、先に GraphQLとは？REST APIとの違いと向いている場面を初心者向けに解説を読むと、API設計の前提がつながりやすいです。

OpenAPIとは何か

OpenAPIは、HTTP APIの仕様を標準的な形式で記述するための仕様です。
OpenAPI Initiativeの仕様では、OpenAPI Specificationは、HTTP APIの能力を人間とコンピューターの両方が理解できるようにする、言語に依存しないインターフェース記述として説明されています。

ざっくり言うと、OpenAPIは APIの取扱説明書を、ツールでも読める形で書くルール です。

OpenAPIで書くと、たとえば次のような情報を1つの仕様書にまとめられます。

APIの基本情報
サーバーURL
エンドポイント
HTTPメソッド
パスパラメータ、クエリパラメータ
リクエストボディ
レスポンス形式
エラー時のレスポンス
認証方式
共通スキーマ

これにより、実装を読まないと分からない 担当者に聞かないと分からない 状態を減らせます。

Swaggerとは何か

Swaggerは、もともとAPI仕様の名前として広く使われていました。
その後、仕様としての名前はOpenAPIになり、Swaggerは主にツール群の名前として残っています。

実務では、今でも Swaggerを見てください Swaggerを書いてください と言われることがあります。
この場合、多くは OpenAPI形式のAPI仕様書 や Swagger UIで表示されたAPIドキュメント を指しています。

整理すると、次の理解で大きく外しません。

名前	ざっくりした意味	実務での見え方
OpenAPI	API仕様を書くための標準仕様	openapi.yaml、openapi.json、API定義ファイル
Swagger	OpenAPIを扱うツール群や旧称として使われる名前	Swagger UI、Swagger Editor、Swagger Codegen

会話ではSwaggerという名前が残りやすいですが、新しく文書化するときは OpenAPI仕様書 と呼ぶ方が誤解は少ないです。

API仕様書に書く内容

OpenAPIの仕様書は、細かく書こうと思えばかなり多くの情報を書けます。
ただ、最初から全部を完璧に埋めようとすると止まりやすいので、まずはチームが困りやすいところから書くのが現実的です。

エンドポイントとHTTPメソッド

まず、どのURLに、どのHTTPメソッドでアクセスするのかを書きます。

たとえば、ユーザー一覧を取得するなら GET /users、ユーザーを作成するなら POST /users のように整理します。
ここが曖昧だと、フロントエンド側もテスト側も実装を進めにくくなります。

リクエスト

次に、リクエストで何を送るのかを書きます。
クエリパラメータ、パスパラメータ、ヘッダー、JSONボディなどを分けて書くと、利用側が迷いにくくなります。

特に、必須項目、任意項目、型、最大文字数、許可される値は重要です。
name は文字列 だけでなく、必須なのか 空文字を許すのか 何文字までか まで決めると、後続の実装が安定します。

レスポンス

レスポンスでは、成功時に返るJSONの形、ステータスコード、エラー時の形式を書きます。
実務では成功時だけでなく、バリデーションエラー、認証エラー、権限エラー、存在しないIDを指定したときの挙動が大事です。

エラー形式が画面ごとに違うと、フロントエンド側の処理が増えます。
共通のエラーレスポンスをOpenAPIに書いておくと、実装レビューでも確認しやすくなります。

認証と権限

API仕様書には、認証方式も書きます。
Bearer token、APIキー、Cookieベースのセッションなど、どの方式で呼ぶのかを明確にします。

ただし、OpenAPIに 認証が必要 と書いただけでは、権限設計までは伝わりません。
本人だけ見られる 管理者だけ更新できる 組織メンバーだけ取得できる のような条件は、説明文や別の設計資料と組み合わせて残す必要があります。

OpenAPIの小さな例

最小限の雰囲気だけ見ると、OpenAPI仕様書は次のような形です。

openapi: 3.2.0
info:
  title: Sample API
  version: 1.0.0
servers:
  - url: https://api.example.com
paths:
  /users/{userId}:
    get:
      summary: Get a user
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A user
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                  - name
                properties:
                  id:
                    type: string
                  name:
                    type: string
        '404':
          description: User not found

この例では、GET /users/{userId} があり、userId が必須のパスパラメータで、成功時は id と name を返し、見つからない場合は404になることが分かります。

本番の仕様書では、共通のレスポンスやスキーマを components に切り出すことが多いです。
同じユーザー形式、同じエラー形式、同じ認証方式を何度も書かずに済むためです。

チームで共有するときの基本

OpenAPI仕様書は、単に作るだけでは効果が薄いです。
チームの開発フローの中で、誰が更新し、いつ確認し、何を正とするのかを決める必要があります。

仕様書の置き場所を決める

まず、仕様書の置き場所を決めます。
リポジトリ内に openapi.yaml として置く、APIサーバーから /openapi.json として出す、SwaggerHubのような専用サービスで管理するなど、方法はいくつかあります。

重要なのは、最新版はどれか が分かることです。
チャットに貼られた古いJSON、ローカルに残ったYAML、実装から自動生成されたファイルが混在すると、仕様書の価値が落ちます。

変更をレビュー対象にする

APIの変更は、コードだけでなく仕様書もレビュー対象にします。
新しいエンドポイントを追加したのにOpenAPIが更新されていない、レスポンス項目を削除したのに仕様書が古い、という状態はよく起きます。

プルリクエストで APIを変えたらOpenAPIも更新する をチェック項目にすると、ズレを減らせます。

実装と仕様書のズレを検出する

できれば、OpenAPIを使ってテストや検証につなげます。
たとえば、レスポンスが仕様書のスキーマに合っているか、必須項目が欠けていないか、想定外の型になっていないかをCIで確認できます。

ここまでできると、OpenAPIは単なるドキュメントではなく、APIの契約を守るためのガードになります。

サンプルを入れる

仕様書には、型だけでなくサンプルもあると理解しやすくなります。
特に、日付形式、金額、ステータス値、エラー形式は、サンプルがあるだけで認識ズレが減ります。

ただし、サンプルだけが正にならないよう注意します。
サンプルは理解の補助であり、必須項目や型の定義はスキーマとして明確に残す方が安全です。

よくある失敗

OpenAPIでよくある失敗は、作ったけれど更新されない ことです。
最初にきれいなSwagger UIを用意しても、実装が進むたびにズレていくと、チームはだんだん見なくなります。

もうひとつは、自動生成に任せすぎることです。
フレームワークからOpenAPIを自動生成する方法は便利ですが、説明文、エラー仕様、業務上の制約、権限条件までは十分に表現されないことがあります。

逆に、手書きだけに寄せすぎると、実装とのズレが起きやすくなります。
現実的には、実装から取れる情報は自動生成し、チームで合意すべき説明やサンプル、エラー方針はレビューで補う、という分担が扱いやすいです。

どこから始めるとよいか

既存APIにOpenAPIを入れるなら、最初から全APIを対象にしなくても大丈夫です。
まずは利用頻度が高いAPI、外部連携に使うAPI、フロントエンドとの認識ズレが起きやすいAPIから始めると効果が見えやすいです。

最初の一歩としては、次の順番が現実的です。

代表的なエンドポイントを3から5本選ぶ
成功レスポンスと主要なエラーを定義する
Swagger UIなどでチームが見られる形にする
API変更時にOpenAPIも更新するルールを入れる
余裕が出たらスキーマ検証やコード生成へ広げる

OpenAPIは、最初から大掛かりなAPI管理基盤を作るためだけのものではありません。
小さく始めても、APIの認識をチームでそろえる という目的には十分役立ちます。

まとめ

OpenAPIは、API仕様書を標準的な形で書き、チームやツールで共有しやすくするための仕様です。
Swaggerは、そのOpenAPI仕様書を表示・編集・生成するツール群の名前として使われることが多いです。

API開発では、実装そのものだけでなく、利用側が何を送ればよいか、何が返るか、エラー時にどう扱えばよいかを共有することが重要です。
OpenAPIを使うと、その共有を口頭や個人メモから、レビュー可能で再利用しやすい仕様書へ移せます。

ただし、仕様書は作って終わりではありません。
API変更と一緒に更新され、実装とのズレを検出でき、チームが普段から参照する状態にしてこそ価値が出ます。

参考リンク

OpenAPI Initiative: OpenAPI Specification v3.2.0
OpenAPI Initiative: What is OpenAPI?
Swagger: What Is the Difference Between Swagger and OpenAPI?