ひとことで
HTTP の API の仕様を YAML・JSON で書く標準の形式。paths に操作を、components に使い回すスキーマを書き、$ref で参照する。
OpenAPI は、HTTP の API のパス・パラメータ・リクエストとレスポンスの形を YAML か JSON で書く標準の形式です（以前の名前は Swagger）。2026年時点では 3.1 系が広く使われ、2025年9月に 3.2.0 も公開されています（3.1 と互換）。1つの仕様書から、ドキュメント・型・モックなどを作れるのが一番の利点です。
最小の例
openapi: 3.1.0
info: { title: Shop API, version: 1.0.0 }
paths:
/orders/{orderId}:
get:
summary: 注文を1件取得
parameters:
- name: orderId
in: path
required: true
schema: { type: string }
responses:
"200":
description: 成功
content:
application/json:
schema: { $ref: "#/components/schemas/Order" }
"404":
$ref: "#/components/responses/NotFound"
/orders:
post:
summary: 注文を作成
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/NewOrder" }
responses:
"201": { description: 作成した }
components:
schemas:
Order:
type: object
required: [id, status, total]
properties:
id: { type: string }
status: { type: string, enum: [pending, paid, shipped] }
total: { type: integer, description: 税込みの金額（円） }
note: { type: [string, "null"] } # 3.1 は null を型で書く
NewOrder:
type: object
required: [itemId, quantity]
properties:
itemId: { type: string }
quantity: { type: integer, minimum: 1 }
responses:
NotFound:
description: ない
content:
application/problem+json:
schema: { type: object }| 要素 | 書くこと |
|---|---|
paths | URL とメソッドごとの操作。{orderId} はパスの変数 |
parameters | パス・クエリ・ヘッダーの値。in と required・schema |
requestBody | 送る本文の形式とスキーマ |
responses | ステータスコードごとの応答。エラーも書く |
components | 使い回す部品（schemas・responses・parameters・securitySchemes） |
$ref | 部品を参照する。同じ形を何度も書かない |
スキーマの部分は JSON Schema の書き方です。3.1 は JSON Schema（2020-12）にそろえられたので、3.0 の nullable: true は type: [string, "null"] と書きます。どの版で書くかは、使う道具の対応を見て決めます。
面接ではこう答える
OpenAPI は、HTTP の API の仕様を YAML か JSON で書く標準の形式です。paths に URL とメソッドごとの操作を書き、parameters・requestBody・responses で入力と出力の形を決めます。何度も出てくるデータの形は components の schemas にまとめて、$ref で参照します。1つの仕様書からドキュメント、クライアントの型、モックサーバーを作れるので、フロントや App のチームと並行して開発しやすくなります。
Webとの関わりAPI を作る・使うときの共通の約束で、フロント・App・他チームとのやりとりのほとんどがこの仕様書を通して行われます。