OpenAPI

OpenAPI とは

OpenAPI は、REST API の仕様を YAML または JSON で記述する標準フォーマットである。エンドポイント、リクエストとレスポンスの構造、認証方式を機械可読な形で書くため、1 本の仕様書からドキュメント・型定義・モックサーバーを同時に導き出せる。

前身は Swagger である。仕様の改訂履歴では Swagger 1.0 の公開が 2011 年 8 月 10 日、Swagger 2.0 が 2014 年 9 月 8 日、そして 2015 年 12 月 31 日に Swagger 2.0 が OpenAPI Initiative へ寄贈された記録が残っており、この寄贈された版が OpenAPI 2.0 に当たる。以後は Linux Foundation 傘下の OpenAPI Initiative が仕様を管理し、Swagger の名は Swagger UI や Swagger Editor といったツール群の名前として残っている。2026 年 8 月時点で公開されている最新版は 3.2.0 (2025 年 9 月 19 日公開) で、3.1 系は 3.1.2、3.0 系は 3.0.4 まで公開されている。「最新は 3.1」型の書き方は数年で古びるので、版に言及するときは公開日も併記しておきたい。

基本的な仕様書

注文作成の 1 エンドポイントを 3.1 系で書くと次のようになる。paths の下がパス、その下が HTTP メソッド、さらにその下にリクエストとレスポンスが並ぶ入れ子構造で、レスポンスはステータスコードごとに分けて書く。複数箇所で使う構造は components/schemas に切り出し、$ref で参照する。

openapi: 3.1.0
info:
  title: Order API
  version: 1.0.0
paths:
  /orders:
    post:
      summary: 注文を作成
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [userId, items]
              properties:
                userId: { type: string }
                items:
                  type: array
                  items: { $ref: '#/components/schemas/OrderItem' }
      responses:
        '201':
          description: 注文が作成された
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }
        '400':
          description: バリデーションエラー
components:
  schemas:
    OrderItem:
      type: object
      required: [sku, quantity]
      properties:
        sku: { type: string }
        quantity: { type: integer, minimum: 1 }
    Order:
      type: object
      properties:
        orderId: { type: string }
        status: { type: string, enum: [pending, paid, shipped] }
        items:
          type: array
          items: { $ref: '#/components/schemas/OrderItem' }

3.0 系と 3.1 系の断層

版番号が 1 つ上がっただけに見えるが、3.0 系と 3.1 系のあいだにはスキーマ記述の方言そのものの断絶がある。3.0 系の Schema Object は JSON Schema Draft Wright-00 を拡張したサブセットで、null を許す型を JSON Schema 流に書けず、独自の nullable フィールドで表した。3.1 系では Schema Object が JSON Schema Draft 2020-12 のスーパーセットと定義され、null は type: [string, null] のように型の配列で書く。nullable というフィールドは 3.1 系の仕様書には存在しない。

必須のトップレベルフィールドも変わった。3.1 系では openapi と info のほかに paths・components・webhooks のうち少なくとも 1 つがあればよく、パスを 1 つも持たないスキーマ定義だけの仕様書や、Webhook だけを記述した仕様書が正式に成立する。

落とし穴は、この断層をツール側が越えられないことである。3.1 で書いた仕様書を 3.0 までしか読まないツールへ渡すと、版の不一致として弾かれるか、型配列の解釈で食い違う。書き始める前に通す予定のツール全部が受け付ける版を調べ、いちばん低い版に合わせるのが安全である。

OpenAPI から生成できるもの

仕様書 1 本を入力にして、次のものはツールが機械的に吐き出せる。手で書くと必ず実装とずれていく部分を生成側へ寄せるのが狙いである。

生成物	ツール
対話的ドキュメント	Swagger UI, Redoc
TypeScript の型定義	openapi-typescript
API クライアント	openapi-generator, orval
サーバースタブ	openapi-generator
バリデーション	openapi-response-validator
モックサーバー	Prism

スキーマファースト vs コードファースト

どちらを選ぶかは、仕様書と実装のどちらを正とみなすかの選択である。

アプローチ	流れ	メリット
スキーマファースト	OpenAPI 仕様書 → コード生成	フロントエンドとバックエンドが並行開発
コードファースト	コード → OpenAPI 仕様書を自動生成	実装が先、素早く開発

API ファーストデザインではスキーマファーストを採る。仕様書が先にあれば、バックエンドの実装を待たずにフロントエンドがモックサーバーと生成済みの型で着手できるうえ、互換性を壊す変更が仕様書の差分としてレビューに載る。ただし生成されたコードを手で直すと次の生成で消えるため、生成物と手書きコードの境界を決めずに始めると運用が崩れる。逆にコードファーストは着手が速い代わりに、実装のうっかりミスまでそのまま仕様として公開されてしまい、互換性を壊したことに気づくのが利用者からの問い合わせ時になりやすい。

API Gateway での活用

API Gateway は OpenAPI 仕様書をインポートして REST API を作成できる。1 つのファイルからエンドポイントをまとめて組み立てられるので、コンソールでの手作業を避けたい場合に効く。

ここに版の落とし穴がある。2026 年 8 月時点の API Gateway 開発者ガイドによれば、REST API のインポートが受け付けるのは OpenAPI v2.0 と v3.0 の定義ファイル (さらに一部の例外あり) で、上に挙げた openapi: 3.1.0 の仕様書はそのままでは通らない。3.1 系で書いているなら、インポート用に 3.0 系へ落とした版を用意するか、最初から 3.0 系で書く判断が要る。しかも型配列で書いた null 許容は 3.0 系では nullable へ書き換えることになるため、版番号を書き換えるだけの機械的な変換では済まない箇所が残る。

TypeScript の型生成

openapi-typescript は仕様書を読んで paths という 1 つの大きな型を吐き出す。エンドポイントごとの型は、その paths をパス・メソッド・content の順に添字で辿って取り出す。

npx openapi-typescript openapi.yaml -o src/api-types.ts

import type { paths } from './api-types';

type CreateOrderBody = paths['/orders']['post']['requestBody']['content']['application/json'];
type OrderResponse = paths['/orders']['post']['responses']['201']['content']['application/json'];

この方式の利点は、型が仕様書の写しではなく仕様書そのものから導かれる点にある。手で型を書き写す運用ではフィールドを 1 つ増やすたびに写し漏れが起きるが、生成なら仕様書を直せば型が追随する。

反面、生成を忘れれば古い型のままビルドが通ってしまう。生成物をリポジトリに含める運用なら、CI で再生成して差分が出たら失敗させる仕組みを入れておくと、仕様書だけ更新されて型が取り残される事故を防げる。添字で辿る書き方は仕様書の構造にそのまま依存するため、requestBody が required でないエンドポイントでは型が省略可能扱いになり、続けて content を添字で引くとエラーになる点にも注意したい。