API・メッセージング

OpenAPI おーぷんえーぴーあい

REST APISwaggerAPIドキュメントスキーマ定義JSON/YAMLAPI設計

OpenAPIについて教えて

簡単に言うとこんな感じ！

APIの「取扱説明書」を書くための共通フォーマットだよ！「このURLにこのデータを送ると、こんな結果が返ってくる」って仕様を統一ルールで書いておくことで、開発チーム間の認識ズレをなくせるんだ！

OpenAPIとは

OpenAPI（オープンエーピーアイ）とは、REST API（ウェブ経由でシステム同士がデータをやり取りする仕組み）の仕様を記述するための標準フォーマットです。もともとは「Swagger（スワッガー）」という名前で知られていたもので、2016年に業界団体「OpenAPI Initiative」に移管されて現在の名称になりました。

APIとは、たとえば「天気予報サービスのデータを自社アプリに取り込む」「決済システムを自社サイトに連携する」といった場面で使われる”システム間のつなぎ口”です。OpenAPIはそのつなぎ口の設計図をYAML（ヤムル）またはJSON（ジェイソン）という形式で書き表す方法を定めており、誰が書いても同じルールで読めるようにしています。

発注担当者にとっての実務的な意義は大きく、「ベンダーにAPIの仕様書をOpenAPI形式で提出してもらう」ことで、ドキュメントの品質がある程度保証され、後から別のベンダーに乗り換えた場合も仕様を引き継ぎやすくなります。いわば「共通語」で書かれた設計書と言えます。

OpenAPIの構造と仕組み

OpenAPI仕様書は、以下のブロックで構成されています。

セクション	役割	例
`info`	APIの基本情報	タイトル・バージョン・説明
`servers`	APIの接続先URL	`https://api.example.com/v1`
`paths`	操作の一覧（エンドポイント）	`/users`, `/orders/{id}`
`components`	再利用可能な部品定義	データ構造（スキーマ）・認証方式
`security`	認証・認可の方式	APIキー・OAuth2など

覚え方：「情サバパコセ」

情報（info）→ サーバー（servers）→ パス（paths）→ コンポーネント（components）→ セキュリティ（security）

この順番でAPIの”取説”が完成するとイメージすると覚えやすいです。

OpenAPI仕様の簡単な例（YAML形式）

openapi: "3.1.0"
info:
  title: 注文管理API
  version: "1.0"
paths:
  /orders/{id}:
    get:
      summary: 注文情報を取得する
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: 注文情報の取得成功

このように、「どのURLに」「何のデータを送ると」「どんな結果が返ってくるか」が一目でわかる形で書かれます。

歴史と背景

2010年 — Tony Tam氏がAPI管理ツール「Wordnik」開発中に「Swagger」を考案。APIドキュメントの自動生成を目指した
2011年 — SwaggerをOSS（オープンソース）として公開。API開発者の間で急速に普及
2015年 — SmartBear社がSwaggerを買収。同年、Linux Foundation傘下に「OpenAPI Initiative（OAI）」が設立され、Google・Microsoft・IBMなど大手も参加
2016年 — 仕様が「Swagger 2.0」から「OpenAPI Specification 3.0（OAS 3.0）」に改名・移管
2021年 — 最新版「OpenAPI 3.1」をリリース。JSONスキーマとの完全互換を実現
現在 — AWS・Azure・GCPなど主要クラウドのAPIも多くがOpenAPI形式で仕様公開。業界標準として定着

Swaggerとの関係・関連ツールの全体像

「Swagger」と「OpenAPI」は混同されがちですが、現在は以下のように整理されています。

OpenAPIを活用したワークフロー比較

方式	流れ	メリット	注意点
Design-First	OpenAPI仕様→実装	仕様を先に合意できる。フロント・バックエンドが並行開発可能	仕様と実装のズレに注意
Code-First	実装→OpenAPI自動生成	すぐ開発を始められる	ドキュメントが後追いになりがち

規格・文書	内容
OpenAPI Specification 3.1	現行の最新仕様。JSONスキーマ Draft 2020-12 と完全互換
OpenAPI Specification 3.0	最も普及しているバージョン。多くのツールが対応
Swagger 2.0	旧称仕様。レガシーシステムでは現役のことも多い
JSON Schema	OpenAPIのデータ型定義の基盤となる規格
RFC 7231	HTTP/1.1の意味論を定義。OpenAPIのHTTPメソッド定義の基礎