真面目にOpenAPI3.0からOpenAPI3.1での変化を把握する

3.0.0, 3.0.1, 3.0.2, 3.0.3 の違いも把握するべきなんだろうか？

release 部分があるのがありがたいのだけど、rcが混ざるのが面倒だな。あと英語を把握するのが面倒なので翻訳したものを貼るべきなんだろうか？

2.0 -> 3.0

OAS 3.0.0-rc0 がリリースされました! プレリリース

OAS 3.0.0 の最初の実装者向けドラフト (3.0.0-rc0 として知られます) のリリースを発表できることを嬉しく思います。

このリリースでは、最初のリリースと同様に多くの変更が加えられているため、変更ログが更新されることが予想されます。変更の最初のリスト (順不同):

• 仕様のバージョン管理スキームを変更しました。
• 仕様内の再利用可能な定義が拡張され、コンポーネント オブジェクトの下に再編成されました。
• 操作コールバックのサポートが追加されました。
• 応答と操作の間の新しい静的リンクのサポートが追加されました。
• パラメーターを再加工 - formData パラメーターを削除し、Cookie パラメーターを追加し、本文パラメーターを別のエンティティとしての要求本文オブジェクトに変更しました。
• パラメーターが複合型をサポートするようになりました。
• 応答は複数のメディア タイプの仕様をサポートします。
• ファイルのサポートが改良されました。fileタイプとしては削除されましたが、ファイルのアップロードとダウンロードの処理が改善されました。
• より多くのスキームをサポートできるようにセキュリティ定義を作り直しました。
• 仕様全体にわたる例のサポートが改善されました。
• URL 変数を含む、API をホストする複数のサーバーを定義するためのサポートが追加されました。

---

OAS 3.0.0-rc1 がリリースされました! プレリリース

OAS 3.0.0-rc1 変更ログ

スキーマの変更

• urlがサーバー オブジェクトの下に必要になりました。
• サーバー変数オブジェクトenumとdefaultその値はのみになりました (以前はstringany でしたprimitive)。
• serversパス項目オブジェクトと操作オブジェクトの下のオブジェクトは、単一ではなくサーバー オブジェクトの配列になるように修正されました。
• exampleおよびフィールドexamplesは、サンプル オブジェクトとともに再加工されました。examplesスキーマ オブジェクトの下にフィールドはなくなりました。存在する場合examples、それらは各例の追加のメタデータを含む名前付き例のマップになります。サンプル オブジェクトにはフィールドが定義されており、自由形式ではありません。
• contentリクエスト本文オブジェクトの下に必須になりました。
• hrefリンク オブジェクトの下の名前が に変更されoperationRef、その説明も明確になりました。
• deprecatedスキーマ オブジェクトの下のフィールドはデフォルトで になりますfalse。
• flowセキュリティ スキーム オブジェクトの下のフィールドの名前が に変更されましたflows。
• リクエストrequired本文のデフォルトは になりましたfalse。
• allowReservedEncoding プロパティ オブジェクトに追加されました。

記述的な変更

• termsOfService現在は URL の形式でなければなりません。
• すべてのdescriptionフィールドが CommonMark をサポートするようになりました。
• 特定の応答コード (200たとえば) が応答範囲 (2XXたとえば) より優先されることを明確にしました。
• パラメータ オブジェクトについては、 またはschemaのいずれかがcontent必須であることを明確にしました。
• patternスキーマ オブジェクトの下で正規表現フレーバーが指定されるようになりました。
• ヘッダーの制限を追加しました。「Accept」、「Content-Type」、「Authorization」ヘッダー パラメーター、および「Content-Type」応答ヘッダーは無視されるようになります。
• サポートされている CommonMark の特定のバージョンを参照しました。
• null(値ではなく) 型ではないことについての説明を追加しました。

文書の変更

• 変更を反映するために目次が更新されました。
• ドキュメント内のさまざまなアンカーを修正しました。
• さまざまな例が修正されました。

---

OAS 3.0.0-rc2 がリリースされました! プレリリース

OAS 3.0.0-rc2 変更ログ

スキーマの変更

• 次のオブジェクトが仕様から削除されました: サーバー変数、コンテンツ、エンコーディング、コールバック、ヘッダー、リンク、リンク パラメーター、スコープ。Mapそれらはすべて、実質的にはそのままの構成に置き換えられています。仕様の拡張は意味をなさないため、許可されないことを明確にします。
• Encoding プロパティ オブジェクトの名前が Encoding オブジェクトに変更されました。これは上記の変更の結果です。
• エンコーディング オブジェクトは、各プロパティがどのメディア タイプに適用されるかを指定するようになりました。
• エンコーディング オブジェクトはheadersヘッダー オブジェクトのマップとして定義されるようになりました。
• の下のさまざまなコンポーネントをComponents Objectインラインで定義することも、参照することもできるようになりました。
• を使用するパラメータではcontent、最大 1 つのメディア タイプのみを使用できるようになりました。
• headersリンク オブジェクトの下のプロパティは削除されました。
• requestBodyリンク オブジェクトには、リクエスト本文を渡すことができる新しいプロパティがあります。
• スキーマ オブジェクトのdiscriminatorプロパティは、新しくサポートされたoneOfと を利用するように完全に作り直されましたanyOf。これらの変更をサポートするために、新しいものがDiscriminator Object追加されました。
• XML オブジェクトはnamespace絶対 URI でなければなりません。
• セキュリティapiKeyスキームも にできるようになりましたcookie。

記述的な変更

• このRich Text Formattingセクションは要件を緩和するために書き直されました。
• OpenAPI定義ファイルの定義を追加しました。
• 空または存在しない場合、デフォルトで値が のservers単一サーバーになることを明確にしました。url/
• 仕様のバージョン管理スキームを説明するセクションを言い換えました。
• Server Variableenumの説明は、文字列のみにできると記載されるように修正されました (型は正しかった)。
• で定義されたパスに対してパスのマッチングがどのように機能するかについての説明と例を追加しましたPaths Object。
• summary操作オブジェクトの下のフィールドの 120 文字制限に関する推奨事項を削除しました。
• formの と のsimpleタイプにさらに詳細が追加されましたstyle。
• エンコーディング オブジェクトがそれらの両方に適用されることと、それらのみに適用されることを明確にしましmultipartたapplication/x-www-form-urlencoded。
• 使用可能な応答コードのワイルドカードが、、、、または のみであることを明確1XXにしまし2XXた。3XX4XX5XX
• 変数式の名前がランタイム式に変更されました。これらはリンクとコールバックの間で統合されており、専用のセクションがあります。その結果、さまざまな例が移動または削除されました。
• ランタイム式は、文字列内で見つかった場合に中括弧を使用するようになりました。
• リンク オブジェクトは、parametersパラメーター名が曖昧な場合の対処方法を定義するようになりました。

文書の変更

• 変更を反映するために目次が更新されました。
• ドキュメント内のさまざまなアンカーを修正しました。
• さまざまな例が修正されました。

文書を読みやすくするために、編集上のさまざまな変更が加えられました。

---

OAS3.0.0がリリースされました！

OAS 3.0.0 変更ログ
OAI は、OpenAPI 仕様 3.0.0 の正式リリースを発表できることを嬉しく思います。

以下のリストは、最後のリリース候補以降の変更を反映しています。

スキーマの変更

• headersエンコーディング オブジェクトの下のマップでもヘッダーを参照できるようになりました。
• 記述的な変更
• 意図を明確にするために説明を言い換えました (意味の変更はありません)。
• OpenAPI 定義ファイルの名前が OpenAPI ドキュメントに変更されました。
• RFC 2119 への準拠を強化するための変更。
• 詳細なリクエスト本文とレスポンスのコンテンツ フィールドは、メディア タイプの範囲をサポートします。
• リンク オブジェクトの下のoperationRefおよびの説明を修正しました。operationIdまた、リンクにはそれらのいずれかを含める必要があることも明確にしました。
• OAuth2 および OpenID Connect の仕様へのリンクを追加しました。

文書の変更

• いくつかの修正例。

3.0.0 -> 3.0.1

OAS 3.0.1 がリリースされました!

OAS 3.0.1 変更ログ
OAI は、OpenAPI 仕様 3.0.1 の正式リリースを発表できることを嬉しく思います。

これは 3.0.0 以降の最初のパッチ リリースであり、次の更新が含まれています。

仕様変更

• 該当する場合、ドキュメントの HTTPS へのリンクを更新しました。
• exampleまた、examplesフィールドの説明が更新され、「オブジェクト」ではなく「フィールド」として参照されるようになりました。
• さまざまな例 (インデント、フィールド名、コメント) を修正しました。
• v3.0.0 の編集中に残っていた Examples オブジェクトを削除しました。仕様内の他のオブジェクトによって使用または参照されていません。
• さまざまなタイプミスを修正しました。

追加の変更点

• Technical Steering Committee (TSC、旧 TDC) の役割とプロセスを明確にしました。
• 開発ガイドラインの改善。

3.0.1 -> 3.0.2

OAS 3.0.2 がリリースされました!

OAS 3.0.2 変更ログ
OAI は、OpenAPI 仕様 3.0.2 の正式リリースを発表できることを嬉しく思います。

パッチリリースとして、読みやすさと正確さの点で仕様を改善するために、次の変更が加えられました。これらの変更はいずれも仕様の動作を変更しません。

• マップ内のキーの大文字と小文字の区別が明確になりました。
• 潜在的な混乱を減らすために、データ型テーブルを再作成し、 を削除しましたCommon Name。
• Server Variable Objectのフィールドの説明を明確にしましたdefault。
• さまざまな例を修正しました。
• Clarified ではoperationId大文字と小文字が区別されます。
• Parameter Objectのdeprecatedフィールドのデフォルト値が であることを明確にしましたfalse。
• Parameter Object'allowEmptyValueフィールドは将来のバージョンで削除されるため、使用しないという推奨事項を追加しました。
• Media Type Objectのフィールドの説明を修正しましたschema。
• Responses Objectの応答コードフィールドの説明を明確にしました。
• Schema ObjectのadditionalPropertiesフィールドのデフォルト値が であることを明確にしましたtrue。
• 説明内の小さな文言の問題を修正しましたDiscriminator Object。
• Security Scheme ObjectCookie での API キーの使用に関する参照を含むように説明を修正しました。

の説明を修正しましたSecurity Requirement Object。

3.0.2 -> 3.0.3

OAS 3.0.3 がリリースされました!

OAS 3.0.3 変更ログ
OAI は、OpenAPI 仕様 3.0.3 の正式リリースを発表できることを嬉しく思います。

パッチリリースとして、読みやすさと正確さの点で仕様を改善するために、次の変更が加えられました。これらの変更はいずれも仕様の動作を変更しません。

• パス テンプレートの仕組みを明確にしました。
• OpenAPI 仕様に適用されるセマンティック バージョニングの意味を明確にしました (これはopenapiフィールドではなくversionフィールドであることに注意してください)。
• 一部のハイパーリンクを から に変更しましhttpたhttps。
• 操作にオプションのセキュリティの概念を追加することを明確にしました。
• Server Variable Object' をenum空にしてはいけないという説明を追加しました。これは重大な変更ではありませんが、次のメジャー バージョンでのより明示的な制限のガイダンスとして考慮する必要があります。
• の下の明確なパスはPaths Objectスラッシュで始める必要があります。
• 兄弟フィールドでのPath Item Objectの動作を明確にしました。$ref
• いくつかの例を修正しました。
• callbacksの下のマップ構造を明確にしましたOperation Object。
• パスパラメータの照合方法を明確にしました。
• exampleの/examples値を明確にしましたParameter Object。
• 値の例を修正しましたpipeDelimited object。
• 説明を修正しましたCallback Object。
• Link ObjectのoperationDef説明を明確にしました。
• の ABNF が改善されましたRuntime Expressions。
• patternunderの有効な正規表現を明確にしましたSchema Object。
• nullableの下の動作を明確にしましたSchema Object。
• の説明内の OAuth2 フローの名前を修正しましたSecurity Scheme Object。
• セクションの説明を改善しましたSecurity Filtering。

3.0.3 -> 3.1.0

OAS 3.1.0-rc0 がリリースされました! プレリリース

変更履歴

このリリースの一環として、私たちは SemVer を今後フォローしないことを決定し、そのため重大な変更を導入します。これらの変更は、リリース ノートの一部として文書化されています。

追加

• 新しいトップレベルフィールド - が導入されましたwebhooks。これにより、API の一部として利用可能なアウトオブバンド Webhook を記述することができます。
• Infoオブジェクトには新しいsummaryフィールドがあります。
• ライセンスオブジェクトにidentifierSPDX ライセンス用の新しいフィールドが追加されました。
• コンポーネント オブジェクトに新しいエントリが追加されpathItems、Path Item Object有効な OpenAPI ドキュメント内で再利用可能な を定義できるようになりました。

拡張機能

• JSON スキーマ仕様ドラフト 2019-09に基づくようにプリミティブ型を更新しました。これには type が含まれるようになりましたnull。
• HTTP 1.1 仕様RFC7231でセマンティクスが明示的に定義されている HTTP メソッドでのみリクエスト ボディを許可するという制限が解除されました。他の方法では許可されていますが、お勧めできません。
• object typeforspaceDelimitedおよび値のサポートが追加されましたpipeDelimited style。
• エンコーディングオブジェクトはstyle、メディア タイプのexplodeおよびallowReservedをサポートするようになりましたmultipart/form-data。
• より良いwebhooksサポートを有効にするために、 の式でCallback ObjectもPath Item Objectを参照できるようになりました。
• Reference Objectを使用する場合、summaryおよびdescriptionフィールドをオーバーライドできるようになりました。
• スキーマオブジェクトは、 JSON スキーマ ドラフト 2019-09 に完全に準拠しました ( 「JSON スキーマ コア」および「JSON スキーマ検証」を参照)。こちらも参照してください。Breaking Changes
• Discriminatorオブジェクトは、仕様拡張機能を使用して拡張できるようになりました。
• mutualTLSセキュリティ方式として相互 TLS ( ) のサポートが追加されました。
• 使用されるセキュリティ要件で、実行に必要なロールの配列 (OAuth 2.0 セキュリティ スキームのスコープだけでなく) を定義できるようになりました。

変更点

• pathsOpenAPI ドキュメントでは、 、 、componentsの少なくとも 1 つがwebhooks最上位に存在する必要があります。以前のバージョンでは必須でしたがpaths、有効な OpenAPI ドキュメントでは Webhook のみ、または再利用可能なコンポーネントのみを記述できるようになりました。したがって、OpenAPI ドキュメントは必ずしも API を記述する必要はなくなりました。
• スキーマ オブジェクトのタイプを持つ 3.0.0 仕様のどこでも| 参照オブジェクトはスキーマ オブジェクトのみに置き換えられました。JSON スキーマの完全サポートへの移行により、$refは本質的に の一部でありSchema Object、独自の動作が定義されています。
• 接頭辞が付いている拡張機能は、x-oas-OpenAPI Initiative 用に予約されています。
• formatはデフォルトでは検証されなくなりました。

重大な変更

• 仕様のバージョン管理は SemVer に従わなくなりました。
• キーワードnullableがから削除されましたSchema Object(nullタイプ値として使用できます)。
• exclusiveMaximumまた、(JSON スキーマに従って) 値exclusiveMinimumを受け入れることはできません。boolean
• JSON スキーマに準拠しているため、リクエストとレスポンスに関連してrequiredとreadOnly/の間のやり取りはなくなりました。writeOnly
• format( byte、binary、またはbase64) は、ファイル ペイロードを記述するために使用されなくなりました。JSON スキーマ準拠の一環として、現在contentEncodingもcontentMediaTypeそのような仕様に使用できます。

説明

• OpenAPI ドキュメントの定義を言い換えて、ドキュメントでパスを記述する必要がなくなり、パス、Webhook、コンポーネント、またはそれらの組み合わせを記述できることを反映しました。
• RESTful API という用語を削除し、HTTP API を使用するようになりました。
• 相対参照の解決が再定義され、明確になりました。スキーマ オブジェクト参照と他のすべてとでは解像度が異なることに注意してください。
• サンプルを改良して新しいフィールド/オブジェクトのコンテキストを提供するためのサンプルの修正。

---

OAS 3.1.0-rc1 がリリースされました! プレリリース

変更履歴

重大な変更がある理由の説明も含め、3.1.0 の以前の変更点については、3.1.0-rc0を参照してください。

重大な変更

• Server Variableはenum空であってはなりません (SHOULD から変更)。
• Server Variableは、そのような値が定義されている場合、その値defaultに存在しなければなりませんenum(SHOULD から変更)。
• responses操作オブジェクトの下で定義する必要はなくなりました。

説明

• パス テンプレート式に対応するパス パラメーターがない場合があることが明確になりました。
• データ型 (および単なるプリミティブ データ型) が JSON スキーマに対応するようになりました。
• さまざまな外観上の修正。
• キーワードを (暗黙的および明示的に)処理する方法を説明する新しいセクションが追加されました$schema。

---

OAS 3.1.0 がリリースされました! 最新

OAI は、OpenAPI 仕様 3.1.0 の正式リリースを発表できることを嬉しく思います。

変更履歴
重大な変更がある理由の説明も含め、3.1.0 の以前の変更点については、3.1.0-rc1 を参照してください。

追加

• jsonSchemaDialectスキーマ オブジェクトのデフォルトの $schema 値を定義できるようにする最上位フィールドが追加されました。

アップデート

• より正確な場所へのリンクをいくつか更新しました。
• JSON スキーマのサポートを最新の2020-12 ドラフトに更新します。
• URI と URL の両方での相対参照解決が改良されました。
• 新しい JSON スキーマ機能を考慮してファイル アップロードの説明を修正しました。これには重大な変更が含まれています。
• x-oai-仕様拡張のとプレフィックスは両方ともx-oas-、OpenAPI Initiative によって定義されるように予約されています。

説明

• パス パラメーター値には、エスケープされていない文字/、?またはを含めることはできません#。
• 参照オブジェクトと JSON スキーマの参照を使用する場所についての詳しい説明。
• 値が URL/URI の場合の表現を統一します。
• $ref参照とコンポーネントの変更を考慮してパス項目を言い換えました。
• いくつかの例を修正しました。
• 一貫性と読みやすさを向上させるために、テキストを若干変更しました。
• 参照オブジェクトの説明が更新され、その動作がさらに明確になりました。
• 最新のドラフトと、デフォルトの OAS 方言としてのhttps://spec.openapis.org/oas/3.1/dialect/baseのデフォルトの使用を考慮して、スキーマ オブジェクトの説明をさらに更新しました。
• 「スキーマ語彙」を「スキーマ方言」に言い換えました。

むしろ json schemaの変更が本丸では？

https://json-schema.org/specification#migrating-from-older-drafts

release note

• draft 2020-12
• draft 2019-09
• draft-07
• draft-06
• draft-05

specificationへのlink

https://json-schema.org/specification-links

binaryがdeprecatedになっていたけれどファイルアップロードはどうするのだっけ？

しっかりそう言う章が存在する。

4.8.14.3 Considerations for File Uploads §

https://spec.openapis.org/oas/v3.1.0.html#considerations-for-file-uploads

これ3.0.3のものでは？？

https://spec.openapis.org/oas/v3.1.0.html#considerations-for-file-uploads
を読んでください。format=binaryは3.0.3までの方法ではないですか？

bing chat (copilot) に聞いた内容があんまり当てにならなかったので隠した。

https://spec.openapis.org/oas/v3.1.0.html#considerations-for-file-uploads

ここくらい読んで答えて欲しい(RAGの貧弱さ...)

In contrast with the 2.0 specification, file input/output content in OpenAPI is described with the same semantics as any other schema type.

In contrast with the 3.0 specification, the format keyword has no effect on the content-encoding of the schema. JSON Schema offers a contentEncoding keyword, which may be used to specify the Content-Encoding for the schema. The contentEncoding keyword supports all encodings defined in [RFC4648], including “base64” and “base64url”, as well as “quoted-printable” from [RFC2045]. The encoding specified by the contentEncoding keyword is independent of an encoding specified by the Content-Type header in the request or response or metadata of a multipart body – when both are present, the encoding specified in the contentEncoding is applied first and then the encoding specified in the Content-Type header.

JSON Schema also offers a contentMediaType keyword. However, when the media type is already specified by the Media Type Object’s key, or by the contentType field of an Encoding Object, the contentMediaType keyword SHALL be ignored if present.

これによってallOfを使ったhackが不要になる。