OpenAPI おーぷんえーぴーあい
API仕様REST APISwaggerスキーマ定義API設計ドキュメント自動生成
OpenAPIについて教えて
簡単に言うとこんな感じ!
OpenAPIはAPIの「取扱説明書の書き方ルール」だよ!「このAPIにこう聞いたらこう返ってくる」っていう仕様を決まった形式で書いておくと、ドキュメントやコードが自動で作れちゃうんだ。開発チームの共通語みたいなものだね!
OpenAPIとは
OpenAPI(オープンエーピーアイ)とは、REST API(Webサービス同士が通信するための仕組み)の仕様を記述するための標準フォーマットのことです。もともとは「Swagger(スワッガー)」という名前でSmartBear社が開発しましたが、2016年にLinux Foundationの傘下に設置されたOpenAPI Initiative(OAI)に寄贈され、オープンな標準規格として整備されました。
YAMLまたはJSONという形式のテキストファイルで「どんなURLに・どんなデータを送ると・どんなデータが返ってくるか」を定義します。この定義ファイル(OpenAPI定義ファイルまたはOpenAPIスペック)があれば、APIのドキュメントを自動生成したり、プログラムの雛形コードを自動生成したり、APIのテストを自動化したりすることができます。
システム発注の現場では、「APIの仕様書をOpenAPIで書いてもらう」と指定することで、開発会社ごとにバラバラなフォーマットで資料が出てくる問題を防ぎ、後々の改修・引き継ぎ・テストが格段にスムーズになります。
OpenAPIの構造と仕組み
OpenAPI定義ファイルは、以下の主要なセクションで構成されます。
| セクション | 役割 | 具体例 |
|---|---|---|
info | APIの名前・バージョン・説明 | ”顧客管理API v1.2” |
servers | APIのベースURL | https://api.example.com/v1 |
paths | エンドポイント(URLのパス)と操作の定義 | /customers にGETでリスト取得 |
components/schemas | データ構造の定義(再利用可能) | Customer: id, name, email |
security | 認証・認可の方式 | APIキー、OAuth2など |
tags | エンドポイントのグルーピング | ”顧客管理”、“注文管理” など |
実際の定義ファイルのイメージ
openapi: 3.1.0
info:
title: 顧客管理API
version: "1.0"
paths:
/customers:
get:
summary: 顧客一覧を取得する
responses:
"200":
description: 取得成功
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Customer"
components:
schemas:
Customer:
type: object
properties:
id:
type: integer
name:
type: string
email:
type: string
OpenAPIのバージョン
現在広く使われているのは以下の2系統です。
| バージョン | 通称 | 特徴 |
|---|---|---|
| OpenAPI 2.0 | Swagger 2.0 | 旧来システムで多く使われる。Swagger時代の名残 |
| OpenAPI 3.0.x | OAS3 | 現在の主流。表現力が大幅に向上 |
| OpenAPI 3.1.0 | OAS3.1 | JSON Schema完全準拠。最新標準 |
歴史と背景
- 2010年 — Wordnik社のTony Tam氏がSwaggerを開発。REST APIのドキュメント作成の煩雑さを解消するために生まれた
- 2015年 — SmartBear社がSwaggerを買収。ツールエコシステムを整備し普及が加速
- 2016年 — SmartBear社がSwagger仕様をLinux Foundation傘下のOpenAPI Initiativeに寄贈。「Swagger 2.0」が「OpenAPI 2.0」に改名。Google・Microsoft・IBMなど主要企業が参加
- 2017年 — OpenAPI 3.0.0リリース。認証まわりやスキーマ表現が大幅に強化
- 2021年 — OpenAPI 3.1.0リリース。JSON Schemaと完全互換になり、WebhookやPathItemの再利用も可能に
- 現在 — AWS・Azure・GCP など主要クラウドのAPIゲートウェイがOpenAPIに対応。事実上のREST API仕様記述の業界標準となっている
関連ツール・技術との比較
OpenAPIは「仕様を書くルール」であり、その定義ファイルを活用するツール群が充実しています。
OpenAPIとGraphQLの違い
| 比較項目 | OpenAPI(REST) | GraphQL |
|---|---|---|
| 通信方式 | HTTPメソッド(GET/POST/PUT等) | 基本的にPOSTのみ |
| データ取得 | エンドポイントごとに固定 | クライアントが欲しいフィールドを指定 |
| 学習コスト | 低め(概念が直感的) | やや高め(独自クエリ言語あり) |
| 仕様記述 | OpenAPI定義ファイル | GraphQLスキーマ |
| 向いている用途 | 汎用的なAPI全般 | 複雑なデータ取得・フロント主導開発 |
発注時のチェックポイント
✅ 「OpenAPI 3.0以上の定義ファイルを納品物に含めること」を仕様書に明記する
✅ Swagger UIなどで定義ファイルを開いて仕様と実装の一致を確認する
✅ OpenAPI Generatorを使ってSDK(利用側のコード)が生成できる状態を要件にする
✅ CI/CDパイプラインにSpectralなどのLintツールを組み込んで品質を保つ
関連する規格・RFC
| 規格・RFC番号 | 内容 |
|---|---|
| OpenAPI Specification 3.1.0 | OpenAPI Initiative が策定する最新の公式仕様 |
| RFC 7231 | HTTP/1.1のセマンティクス(GETやPOSTなどのメソッド定義) |
| RFC 7807 | REST APIのエラーレスポンス形式の標準(Problem Details) |
| RFC 6749 | OAuth 2.0(OpenAPIのsecurityセクションで多用される認証方式) |
関連用語
- REST API — URLとHTTPメソッドを使ってデータをやり取りするAPI設計スタイル
- API — ソフトウェア同士が機能を呼び出し合うための接続口
- JSON — OpenAPI定義ファイルの記述形式の一つ。軽量なデータ交換フォーマット
- YAML — OpenAPI定義ファイルで最もよく使われる人間に読みやすい記述形式
- Swagger — OpenAPIの旧称およびOpenAPIツール群のブランド名
- APIゲートウェイ — APIの入口を一元管理するミドルウェア。OpenAPIをインポートして使える
- GraphQL — REST APIの代替となるクエリ言語ベースのAPI通信方式
- OAuth — APIの認可(アクセス権限の委譲)に使われる標準プロトコル