Swagger 파일 (YAML)의 설명이 오버로드 됨

Question

필자의 멋진 파일을 쓰는데 문제가 있습니다. 필자가 매개 변수를 설명 할 때이 동일한 매개 변수의 $ ref에 대한 설명으로 설명이 오버로드됩니다 (아래 예 참조).

a-body: 
    description: The body 
    type: object 
    properties: 
     my_param: 
     description: Full description 
     $ref: '#/definitions/reference' 

definitions: 
    reference: 
     type: object 
     required: [req] 
     description: an http reference 
     properties: 
      req: 
      type: string 

결과 : 이 the description is overloaded

누군가가 나를이를 통해하시기 바랍니다 얻을 도와 드릴까요?

Answer 1

$ref은 형제 속성을 모두 덮어 씁니다. 이는 $ref의 작동 방식입니다.

my_param: 
    description: Full description 
    allOf: 
    - $ref: '#/definitions/reference' 

다음은 Swagger Editor 및 Swagger UI에서 작동합니다.

다른 속성과 $ref을 결합하는 더 좋은 방법을 제공하기 위해 OpenAPI 사양 저장소에 feature request이 있습니다.