`map`オブジェクトのプロパティ名にOpenAPI 3（Swagger）仕様書を書くには？

Question

私が記述しようとしているAPIには、ルートオブジェクトが任意の数の子オブジェクト（オブジェクト自体のプロパティ）を含むことができる構造があります。ルートオブジェクト内の「キー」またはプロパティは、子オブジェクトの一意の識別子であり、値は子オブジェクトのデータの残りの部分です。

{ 
    "child1": { ... bunch of stuff ... }, 
    "child2": { ... bunch of stuff ... }, 
    ... 
} 

これは、同様の配列、例えばとしてモデル化することができます、それは構造的にあまり明確何識別プロパティがあると暗黙的ではなく、明示的な子供のIDの中で一意になります両方

[ 
    { "id": "child1", ... bunch of stuff ... }, 
    { "id": "child2", ... bunch of stuff ... }, 
    ... 
] 

が、この私たちはオブジェクトやマップを使いたいと思っています。

私はModel with Map/Dictionary PropertiesのSwaggerドキュメントを見てきましたが、それは私の使用事例に適するものではありません。何か書く：

これが十分プロパティの値の記述性を伝えるが、どのように私は制限が「キーのあるものを文書化します：

"Parent": { 
    "additionalProperties": { 
    "$ref": "#/components/schemas/Child", 
    } 

すると、このような何かを生み出します"オブジェクト内に？理想的には、「それはちょうど任意の文字列ではなく、それは子供に対応するIDです」というようなことを言いたいと思います。これはどんな方法でもサポートされていますか？

Answer 1

あなたの例は正しいです。

どのようにオブジェクトの「キー」に対する制限が文書化されていますか？理想的には、「それはちょうど任意の文字列ではなく、それは子供に対応するIDです」というようなことを言いたいと思います。これはどんな方法でもサポートされていますか？

OpenAPIでは、キーが文字列であると想定していますが、キーの内容/形式を制限する方法はありません。モデル番号descriptionでは、制限事項や詳細を口頭で文書化することができます。スキーマの例を追加すると、マップの外観を示すのに役立ちます。

"Parent": { 
    "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 ... }, 
    } 

キーの形式を定義することが可能になるスキーマでsupport for patternPropertiesを追加するための提案は、もあります。しかし、OpenAPI 3.0.0以降、まだ提案段階にあります。