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)、リクエストボディ、およびレスポンスの記述
• Schema Objects (JSON Schema Draft 2020-12 dialect)、コンポーネント、およびリファレンスの使用
• セキュリティスキーム (apiKey、http、mutualTLS、oauth2、openIdConnect) とセキュリティ要件の設定
• メディアタイプ、エンコーディング (form、multipart)、および例 (dataValue/serializedValue/externalValue) の操作

コアリファレンス

トピック	説明	リファレンス
OpenAPI Object	ルートオブジェクト、openapi、$self、info、servers、paths、webhooks、components、security、tags	core-openapi-object
Format & Structure	JSON/YAML、大文字小文字区別、リッチテキスト、OAD 構造、パーシング、ベース URI	core-format-and-structure
Fixed & Patterned Fields	固定フィールド vs パターンフィールド、paths キー、components キー、拡張 (x-)	core-fixed-patterned-fields
Info & Metadata	Info、Contact、License オブジェクト	core-info-metadata
Server	Server Object、Server Variable、URL テンプレート	core-server
Paths & Operations	Paths Object、Path Item、Operation Object、additionalOperations、query	paths-and-operations
Path Templating	パステンプレート、パスパラメータ、マッチング、ABNF	core-path-templating
Parameters	Parameter Object、in (path/query/header/cookie/querystring)、style、schema vs content	parameters
Request Body & Media Type	Request Body、Media Type Object、sequential media types、itemSchema	request-body-and-media-type
Encoding Object	名前/位置によるエンコーディング、contentType、style、explode、form、multipart	core-encoding-object
Media Types	Content キー、メディアタイプ範囲、OpenAPI Media Type Registry	core-media-types
Responses	Responses Object、Response Object、headers、content、links	responses
HTTP Status Codes	Response キー、default、1XX–5XX 範囲 with X	core-http-status-codes
Schema & Components	Schema Object (JSON Schema 2020-12)、Components、$ref 解決	schema-and-components
Schema JSON Schema Keywords	JSON Schema 2020-12 キーワードと Schema 内の OAS 拡張	schema-json-schema-keywords
Schema Composition & Polymorphism	allOf、oneOf、anyOf、discriminator	schema-composition-polymorphism
Data Types & Formats	JSON Schema 型、format キーワード、OAS dialect	core-data-types-and-formats
Discriminator & XML	Discriminator Object、XML Object (nodeType、name、namespace)	core-discriminator-and-xml
Components Reuse	パラメータ、レスポンス、スキーマの $ref による再利用	components-reuse
Reference Object	$ref、summary/description オーバーライド、解決ルール	core-reference-object
Header Object	レスポンス/multipart ヘッダ、style simple、Set-Cookie、Link	core-header-object
Example Object	dataValue、serializedValue、value、externalValue、例の操作	core-example-object
Tag & External Docs	Tag Object、External Documentation Object、parent、kind	core-tags-and-external-docs
Link Object	operationRef、operationId、parameters、requestBody	core-link-object
Runtime Expressions	$request、$response、$url、$method、ABNF、Link/Callback 使用	core-runtime-expressions
Security	Security Scheme、OAuth Flows、Security Requirement Object	security
Security Scheme Types	apiKey、http (basic/bearer)、mutualTLS、oauth2、openIdConnect	security-scheme-types
Security Requirement Object	OR/AND セマンティクス、{} オプション、[] クリア、scopes	security-requirement-object
OAuth2 Flows	OAuth Flows Object、OAuth Flow Object、authorizationCode、deviceAuthorization	security-oauth2-flows
Callbacks & Webhooks	Callback Object、webhooks	callbacks-and-webhooks
Extensions	Specification extensions (x-)、拡張レジストリ	advanced-extensions

ベストプラクティス

トピック	説明	リファレンス
Spec 作成	operationId、tags、$self、components 再利用、responses、security	best-practices-spec-authoring

高度なトピック

トピック	説明	リファレンス
Base URI & Resolution	$self、retrieval URI、リファレンス解決、パーシングガイダンス	advanced-base-uri-and-resolution
Security Filtering	空の Paths/Path Item、セキュリティに関する考慮事項	advanced-security-filtering

主要ポイント

• OAS 3.2 のルートは openapi: 3.2.0 を使用; components、paths、または webhooks の少なくとも 1 つが存在する必要があります。
• $self はドキュメントのベース URI を提供し、リファレンス解決に使用されます。マルチドキュメント OAD で使用してください。
• Schema Object は JSON Schema Draft 2020-12 のスーパーセット。空のスキーマ = true、なし = false。
• Parameter: schema + style または content (1 つのメディアタイプ) のいずれかを使用; in: "querystring" は content が必須です。
• ルートレベルのセキュリティは OR (Security Requirement Objects のいずれか); オペレーション単位でオーバーライド可能; {} = オプション。

<!-- Source: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.2.0.md -->