REST APIを設計・連携していると、次のような疑問にぶつかることはありませんか？
-
「このREST API、OpenAPI仕様なの？」
-
「OpenAPIじゃないAPIって仕様は何で定義されてるの？」
-
「JSON SchemaってOpenAPIと何が違う？」
特に業務システムや外部連携の現場では、OpenAPIが使われていないREST APIも数多く存在します。
この記事では、REST API設計で迷わないために、OpenAPI・独自定義・JSON Schemaの違いを整理して解説します。
そもそもREST APIの「仕様」とは何か？
まず前提として、REST APIにおける「仕様」とは、主に次の情報を指します。
-
エンドポイント（URL）
-
HTTPメソッド（GET / POST など）
-
リクエストパラメータ
-
レスポンス構造（JSON）
-
認証方式
-
エラー仕様
これらをどの形式で定義・共有しているかが「API仕様の違い」になります。
OpenAPIとは
OpenAPIの概要
OpenAPI（旧Swagger）は、REST APIの仕様を YAML / JSON 形式で機械可読に定義できる仕様です。
|
1 2 3 4 5 6 7 |
openapi: 3.0.3 paths: /users: get: responses: '200': description: OK |
OpenAPIの特徴
-
API全体を一元定義できる
-
ドキュメント自動生成が可能
-
クライアント／サーバコード生成に対応
-
仕様の齟齬が起きにくい
向いているケース
-
新規API開発
-
外部公開API
-
チーム開発・長期運用
独自定義（設計書ベース仕様）
独自定義とは
Excel、Word、PDF、社内Wikiなどで作成された 人間向けのAPI設計書です。
よくある構成
-
API一覧表（URL・メソッド）
-
パラメータ一覧（日本語説明）
-
JSONのサンプルレスポンス
特徴
-
日本の業務システムで最も多い
-
非エンジニアにも読みやすい
-
フォーマットが自由
デメリット
-
機械可読ではない
-
実装と仕様がズレやすい
-
自動テストや生成ができない
👉 「OpenAPIですか？」と聞かれて詰まる原因の大半がこれ
JSON Schemaとは
JSON Schemaの概要
JSON Schemaは、JSONデータ構造を定義するための仕様です。
|
1 2 3 4 5 6 7 |
{ "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } |
特徴
-
データ構造の定義に特化
-
バリデーションに強い
-
OpenAPIの内部でも利用されている
注意点
-
API全体（URLやHTTPメソッド）は定義できない
-
単体ではREST API仕様とは言えない
👉 「レスポンスだけJSON Schemaで管理」している現場は意外と多い
OpenAPI・独自定義・JSON Schemaの違いまとめ
| 項目 | OpenAPI | 独自定義 | JSON Schema |
|---|---|---|---|
| API全体定義 | ◎ | ○ | × |
| 機械可読 | ◎ | × | ◎ |
| 自動生成 | ◎ | × | △ |
| 可読性 | ○ | ◎ | △ |
| 現場遭遇率 | 高 | 非常に高 | 中 |
実務でよくある組み合わせ
実際の現場では、単独利用よりも併用されるケースが多いです。
-
独自設計書 ＋ JSON Schema
-
OpenAPI ＋ 補足資料（Excel）
-
OpenAPI未導入だが将来移行予定
模範的な説明例（実務向け）
本APIはOpenAPIは未採用で、
設計書ベースの独自仕様を使用しています。
レスポンス構造の一部はJSON Schemaで定義しています。
この説明で ほぼ100%通じます。
OpenAPIかどうかを見分ける方法
一番簡単な判断方法はこれです。
-
openapi: 3.x.xが書かれたYAML / JSONが存在する
→ OpenAPI -
Excel / Word / Wikiのみ
→ 独自定義 -
JSON Schemaファイルのみ
→ データ仕様のみ定義
REST API設計で迷わないための結論
-
REST API仕様は OpenAPIだけではない
-
日本の業務システムでは 独自定義が今も主流
-
JSON Schemaは 補助的な役割
-
新規設計ならOpenAPIがベスト
-
既存APIなら「何で定義されているか」を正確に説明できることが重要
まとめ
REST API設計で重要なのは、
「どの仕様を使っているか」ではなく「どう説明できるか」です。
OpenAPI・独自定義・JSON Schemaの違いを理解しておけば、
設計・レビュー・外部連携で迷うことはありません。