`map` 객체의 속성 이름에 OpenAPI 3 (Swagger) 스펙을 쓰는 방법은 무엇입니까?

Question

설명하려고하는 API에는 루트 객체가 임의의 수의 자식 객체 (객체 자체의 속성)를 포함 할 수있는 구조가 있습니다. 루트 객체의 "키"또는 속성은 하위 객체의 고유 식별자이며 값은 하위 객체의 나머지 데이터입니다. ,

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

하지만이 모두가 식별 속성이 아니라 명시 적보다는 암시 아이들의 ID 고유성이 구조적으로 명확하지 무엇이며 수 있습니다 :

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

이

마찬가지로 예를 들어, 배열로 모델링 할 수있다 그래서 우리는 객체 또는지도를 사용하려고합니다.

Model with Map/Dictionary Properties에 대한 스와거 설명서를 보았지만 사용 사례에 맞지 않습니다. 같은 것을 쓰기 :

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

하면이 같은 것을 나타냅니다 :

이 적절히 속성 값의 descriptiveness을 전달,하지만 어떻게 제한은 "키 무엇 문서화 않습니다 "물건에? 이상적으로는 "어떤 임의의 문자열이 아니라 아이에게 해당하는 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부터는 여전히 제안 단계에 있습니다.