openapi-specification-v3.2

OpenAPI Specification 3.2

OpenAPI Specification 3.2.0 のエージェント向けリファレンスです。OpenAPI 記述（OAD）の編集、生成、検証に使用します。

使用する場面

• OpenAPI 3.2 の YAML／JSON ドキュメントを作成または更新する場合
• 複数のドキュメントで構成された OAD で、$ref、$self、相対 URI を解決する場合
• パス、オペレーション、パラメーター（query／path／header／cookie／querystring）、リクエストボディ、レスポンスを記述する場合
• スキーマオブジェクト（JSON Schema Draft 2020-12 dialect）、コンポーネント、参照を使用する場合
• セキュリティスキーム（apiKey、http、mutualTLS、oauth2、openIdConnect）と要件を設定する場合
• メディアタイプ、エンコーディング（form、multipart）、例（dataValue／serializedValue／externalValue）を扱う場合

主なリファレンス

トピック	説明	リファレンス
OpenAPI オブジェクト	ルートオブジェクト、openapi、$self、info、servers、paths、webhooks、components、security、tags	core-openapi-object
形式と構造	JSON/YAML、大文字と小文字の区別、リッチテキスト、OAD の構造、解析、ベース URI	core-format-and-structure
固定フィールドとパターンフィールド	固定フィールドとパターンフィールド、paths のキー、components のキー、拡張（x-）	core-fixed-patterned-fields
Info とメタデータ	Info オブジェクト、Contact オブジェクト、License オブジェクト	core-info-metadata
サーバー	Server オブジェクト、Server Variable、URL テンプレート	core-server
パスとオペレーション	Paths オブジェクト、Path Item、Operation オブジェクト、additionalOperations、クエリ	paths-and-operations
パステンプレート	パステンプレート、パラメーター、マッチング、ABNF	core-path-templating
パラメーター	Parameter オブジェクト、in（path/query/header/cookie/querystring）、style、schema と content の比較	parameters
リクエストボディとメディアタイプ	Request Body、Media Type オブジェクト、メディアタイプの順序、itemSchema	request-body-and-media-type
Encoding オブジェクト	名前／位置によるエンコード、contentType、style、explode、form、multipart	core-encoding-object
メディアタイプ	content のキー、メディアタイプの範囲、OpenAPI Media Type Registry	core-media-types
レスポンス	Responses オブジェクト、Response オブジェクト、headers、content、links	responses
HTTP ステータスコード	レスポンスのキー、default、X を使った 1XX～5XX の範囲	core-http-status-codes
スキーマとコンポーネント	Schema オブジェクト（JSON Schema 2020-12）、Components、$ref の解決	schema-and-components
Schema の JSON Schema キーワード	JSON Schema 2020-12 のキーワードと Schema 内の OAS 拡張	schema-json-schema-keywords
スキーマの合成とポリモーフィズム	allOf、oneOf、anyOf、discriminator	schema-composition-polymorphism
データ型とフォーマット	JSON Schema の型、format キーワード、OAS ダイアレクト	core-data-types-and-formats
Discriminator と XML	Discriminator オブジェクト、XML オブジェクト（nodeType、name、namespace）	core-discriminator-and-xml
コンポーネントの再利用	$ref によるパラメーター、レスポンス、スキーマの再利用	components-reuse
Reference オブジェクト	$ref、summary/description のオーバーライド、解決ルール	core-reference-object
Header オブジェクト	レスポンス／multipart のヘッダー、style simple、Set-Cookie、Link	core-header-object
Example オブジェクト	dataValue、serializedValue、value、externalValue、例の使用方法	core-example-object
Tag と外部ドキュメント	Tag オブジェクト、External Documentation オブジェクト、parent、kind	core-tags-and-external-docs
Link オブジェクト	operationRef、operationId、parameters、requestBody	core-link-object
ランタイム式	$request、$response、$url、$method、ABNF、Link／Callback での使用	core-runtime-expressions
セキュリティ	Security Scheme、OAuth Flows、Security Requirement オブジェクト	security
Security Scheme の型	apiKey、http（basic/bearer）、mutualTLS、oauth2、openIdConnect	security-scheme-types
Security Requirement オブジェクト	OR／AND のセマンティクス、{} は任意、[] はクリア、スコープ	security-requirement-object
OAuth2 フロー	OAuth Flows オブジェクト、OAuth Flow オブジェクト、authorizationCode、deviceAuthorization	security-oauth2-flows
コールバックと Webhook	Callback オブジェクト、webhooks	callbacks-and-webhooks
拡張	仕様の拡張（x-）、拡張レジストリ	advanced-extensions

ベストプラクティス

トピック	説明	参照
仕様の作成	operationId、tags、$self、components の再利用、レスポンス、セキュリティ	best-practices-spec-authoring

詳細

トピック	説明	参照
ベース URI と解決	$self、取得 URI、参照の解決、解析のガイダンス	advanced-base-uri-and-resolution
セキュリティフィルタリング	空の Paths／Path Item、セキュリティに関する考慮事項	advanced-security-filtering

要点

• OAS 3.2 のルートでは openapi: 3.2.0 を使用します。components、paths、webhooks のうち、少なくとも 1 つが MUST です。
• $self は参照解決のためにドキュメントのベース URI を指定します。複数ドキュメントの OAD で使用してください。
• Schema Object は JSON Schema Draft 2020-12 のスーパーセットです。空のスキーマは true、なしは false です。
• Parameter：schema+style または content（Media Type は 1 つ）のいずれかを使用します。in: "querystring" には content が必要です。
• ルートの Security は OR（Security Requirement Object のいずれか）です。オペレーションごとに上書きでき、{} は任意を意味します。