openapi-specification-v2

OpenAPI Specification 2.0（旧称 Swagger 2.0）は、パス、オペレーション、パラメーター、レスポンス、スキーマ、セキュリティなど、RESTful API を記述するための JSON/YAML 形式を定義します。Swagger 2.0 の仕様書を作成・編集する場合、構造を検証する場合、または仕様書からコードやドキュメントを生成する場合に、このスキルを使用します。

このスキルは、2026-01-30 に生成された OpenAPI Specification 2.0 に基づいています。

コアリファレンス

トピック	説明	リファレンス
形式と構造	ドキュメント形式、ファイル構造、データ型	core-format-and-structure
固定フィールドとパターン化フィールド	スキーマ内の固定フィールド名とパターン化フィールド名	core-fixed-patterned-fields
Swagger オブジェクト	ルートドキュメント、必須／任意フィールド、拡張機能	core-swagger-object
情報とメタデータ	Info、Contact、License オブジェクト	core-info-metadata
タグと外部ドキュメント	Tag オブジェクト、External Documentation オブジェクト	core-tags-and-external-docs
Reference オブジェクト	$ref、JSON Pointer、同一ドキュメントおよび外部ファイルの参照	core-reference-object
データ型とフォーマット	プリミティブ型、フォーマット表、検証、ファイル型	core-data-types-and-formats
MIME タイプ	consumes/produces、RFC 6838、例	core-mime-types
HTTP ステータスコード	レスポンスキー、デフォルトレスポンス、IANA/RFC 7231	core-http-status-codes
パスのテンプレート化	波括弧、パスパラメーター、名前の照合	core-path-templating
Header オブジェクト	レスポンスヘッダーの定義（type、format、items、検証）	core-header-object
Headers オブジェクト	レスポンスヘッダーのコンテナー（名前 → Header オブジェクト）	core-headers-object
Items オブジェクト	ボディ以外の配列項目（パラメーター、ヘッダー）	core-items-object
Example オブジェクト	MIME タイプ別のレスポンス例	core-example-object

パスとオペレーション

トピック	説明	リファレンス
パスとオペレーション	Paths オブジェクト、Path Item、Operation オブジェクト	paths-and-operations
Path Item $ref	外部パス定義、競合時の動作	path-item-ref

パラメーターとレスポンス

トピック	説明	リファレンス
パラメーター	パラメーターの場所（path、query、header、body、formData）	parameters
collectionFormat	csv、ssv、tsv、pipes、multi とそれぞれの適用対象	parameters-collection-format
パラメーター定義（再利用）	ルートレベルのパラメーター、$ref による再利用	parameters-definitions-reuse
レスポンス	Responses オブジェクト、Response オブジェクト	responses
レスポンス定義（再利用）	ルートレベルのレスポンス、$ref による再利用	responses-definitions-reuse

スキーマと定義

トピック	説明	リファレンス
スキーマと定義	Schema オブジェクト、Definitions、合成、ポリモーフィズム	schema-and-definitions
Schema の JSON Schema キーワード	JSON Schema Draft 4 のサブセットと Swagger 固有のフィールド	schema-json-schema-keywords

セキュリティ

トピック	説明	参照
セキュリティ	セキュリティ定義、セキュリティスキーム	security
セキュリティ要件オブジェクト	ルート／操作でのセキュリティの適用、OR／AND ロジック	security-requirement-object
スコープオブジェクト	OAuth2 のスコープ名 → 説明	security-scopes-object
Basic と API キー	basic および apiKey のセキュリティスキーム	security-basic-apikey
OAuth2 フロー	implicit、password、application、accessCode、および必須 URL	security-oauth2-flows

ベストプラクティス

トピック	説明	参照
仕様の作成	operationId、tags、responses、parameters、definitions、security	best-practices-spec-authoring

高度な内容

トピック	説明	参照
ベンダー拡張	x- プレフィックス、値の型、使用可能な箇所	advanced-vendor-extensions
セキュリティフィルタリング	アクセス制御のための空の Paths、空の Path Item	advanced-security-filtering
拡張機能と XML	スキーマプロパティ用の XML オブジェクト	advanced-extensions-and-xml