メインコンテンツまでスキップ

仕様

バージョン​

OpenAPI 仕様はmajor. minor.patchバージョン管理スキームでバージョーリングされます。major. minorバージョン文字列の部分 (例: 3.1) は、OAS 機能セットを指定するものとします。.patchバージョンは、機能セットではなく、このドキュメントのエラーに対処するか、説明を提供します。OAS 3.1 をサポートするツールは、すべての OAS 3.1.* バージョンと互換性がある必要があります。パッチのバージョンは、ツールによって考慮されるべきではありません。たとえば3.1.0、 と3.1.1を区別しないでください。

場合によっては、提供されるメリットに比べて影響が低いと考えられる OAS のminorバージョンで、下位互換性のない変更が行われることがあります。

OAS 3.*.* と互換性のある OpenAPI ドキュメントには、使用する OAS のバージョンを指定する必須openapiフィールドが含まれています。

フォーマット​

OpenAPI 仕様に準拠する OpenAPI ドキュメント自体は JSON オブジェクトであり、JSON または YAML 形式で表現できます。

たとえば、フィールドに配列値がある場合、JSON 配列表現が使用されます。

{   "field": [ 1, 2, 3 ]}

仕様内のフィールド名はすべて大文字と小文字が区別されます。これには、キーが大文字と小文字を区別しないことが明示的に示されている場合を除き、マップ内でキーとして使用されるすべてのフィールドが含まれます。

スキーマは 2 種類のフィールドを公開します。宣言された名前を持つ固定フィールドと、フィールド名の正規表現パターンを宣言するパターン化フィールドです。

パターン化されたフィールドには、それを含むオブジェクト内で一意の名前が必要です。

YAML 形式と JSON 形式の間で往復する機能を維持するために、いくつかの追加の制約とともにYAML バージョン1.2を使用することが推奨されます。

注: API は YAML または JSON 形式の OpenAPI ドキュメントによって定義できますが、API リクエストとレスポンスの本文、およびその他のコンテンツは JSON または YAML である必要はありません。

文書構造​

OpenAPI ドキュメントは、作成者の裁量により、単一のドキュメントで構成することも、複数の接続された部分に分割することもできます (MAY)。後者の場合、Reference Objects。Schema Object $refキーワードが使用されます。

ルート OpenAPI ドキュメントには、openapi.jsonまたはopenapi.yamlという名前を付けることが推奨されます。

データ型​

OAS のデータ型は、JSON スキーマ仕様ドラフト 2020-12でサポートされている型に基づいています。integer型としてもサポートされており、分数や指数部分のない JSON 数値として定義されることに注意してください。モデルは、JSON スキーマ仕様ドラフト 2020-12 のスーパーセットであるSchema Objectを使用して定義されます。

JSON スキーマ検証ボキャブラリーで定義されているように、データ型にはオプションの修飾子プロパティを持つことができますformat。OAS は、プリミティブ データ型の詳細を提供する追加の形式を定義します。

OAS によって定義されている形式は次のとおりです。

typeformatコメント
integerint32符号付き 32 ビット
integerint64符号付き 64 ビット (別名ロング)
numberfloat
numberdouble
stringpassword入力を分かりにくくするための UI へのヒント。

リッチテキストの書式設定​

仕様全体を通じて、descriptionフィールドは CommonMark マークダウン形式をサポートしていると記載されています。OpenAPI ツールがリッチ テキストをレンダリングする場合は、少なくともCommonMark 0.27で記述されているマークダウン構文をサポートしなければなりません (MUST) 。ツールは、セキュリティ上の懸念に対処するために、一部の CommonMark 機能を無視することを選択してもよい(MAY)。

URI 内の相対参照​

特に指定しない限り、URI であるすべてのプロパティは、RFC3986で定義されている相対参照であってもよい (MAY) 。

Reference Objects、PathItem Object $refフィールド、Link Object operationRefフィールド、およびExample Object externalValueフィールド内の参照を含む相対参照は、 RFC3986に従って参照ドキュメントをベース URI として使用して解決されます。

URI にフラグメント識別子が含まれている場合、そのフラグメントは参照ドキュメントのフラグメント解決メカニズムに従って解決される必要があります。参照されるドキュメントの表現が JSON または YAML である場合、フラグメント識別子はRFC6901に従って JSON ポインターとして解釈されるべきです (SHOULD) 。

JSON スキーマ仕様ドラフト 2020-12で説明されているように、Schema Objectsの相対参照(値は$idとして表示されるものを含む) は、最も近い親$idをベース URI として使用します。親スキーマに $idが含まれていない場合は、ベース URI をRFC3986に従って決定する必要があります。