私が説明しようとしている API は、ルート オブジェクトに任意の数の子オブジェクト (それ自体がオブジェクトであるプロパティ) を含めることができる構造を持っています。ルート オブジェクトの「キー」またはプロパティは、子オブジェクトの一意の識別子であり、値は子オブジェクトの残りのデータです。
{
"child1": { ... bunch of stuff ... },
"child2": { ... bunch of stuff ... },
...
}
これも同様に配列としてモデル化できます。例:
[
{ "id": "child1", ... bunch of stuff ... },
{ "id": "child2", ... bunch of stuff ... },
...
]
しかし、これでは識別プロパティが何であるかが構造的に不明瞭になり、子の ID 間の一意性が明示的ではなく暗黙的になるため、オブジェクトまたはマップを使用する必要があります。
Swaggerのドキュメントを見ましたマップ/辞書プロパティを持つモデルしかし、これは私のユースケースには適していません。次のように記述します。
"Parent": {
"additionalProperties": {
"$ref": "#/components/schemas/Child",
}
次のような結果になります:
これはプロパティの値の説明性を適切に伝えますが、オブジェクト内の「キー」の制限をどのように文書化すればよいでしょうか。理想的には、「これは単なる任意の文字列ではなく、子に対応する ID です」というようなことを言いたいのですが。これは何らかの形でサポートされていますか?
ベストアンサー1
あなたの例は正しいです。
オブジェクトの「キー」の制限事項を文書化するにはどうすればよいでしょうか。理想的には、「これは単なる任意の文字列ではなく、子に対応する ID です」というようなことを言いたいのですが。これは何らかの形でサポートされていますか?
オープンAPI3.1
OAS 3.1はJSON Schema 2020-12を完全にサポートしており、patternPropertiesこのキーワードを使用すると、正規表現を使用して辞書キーの形式を定義できます。
"Parent": {
"type": "object",
"patternProperties": {
"^child\d+$": {
"$ref": "#/components/schemas/Child"
}
},
"description": "A map of `Child` schemas, where the keys are IDs that correspond to the child"
}
または、プロパティ名が列挙型で定義されている場合は、次のように使用できます。propertyNamesその列挙型を定義するには:
"Parent": {
"type": "object",
"propertyNames": {
"enum": ["foo", "bar"]
},
"additionalProperties": {
"$ref": "#/components/schemas/Child"
}
}
OpenAPI 3.0 および 2.0
辞書のキーは文字列であると想定されていますが、キーの内容や形式を制限する方法はありません。 制限や詳細は、スキーマで口頭で文書化できます。descriptionスキーマの例を追加すると、辞書やマップがどのようになるかがわかりやすくなります。
"Parent": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/Child"
},
"description": "A map of `Child` schemas, where the keys are IDs that correspond to the child",
"example": {
"child1": { ... bunch of stuff ... },
"child2": { ... bunch of stuff ... },
}
可能なキー名がわかっている場合 (たとえば、列挙型の一部である場合)、辞書を通常のオブジェクトとして定義し、キーを個々のオブジェクト プロパティとして定義できます。
// Keys can be: key1, key2, key3
"Parent": {
"type": "object",
"properties": {
"key1": { "$ref": "#/components/schemas/Child" },
"key2": { "$ref": "#/components/schemas/Child" },
"key3": { "$ref": "#/components/schemas/Child" }
}
}
"additionalProperties": false次に、それらのキーのみが使用されるように追加することができます。