Swagger / OpenAPI-$ ref를 사용하여 재사용 가능한 정의 매개 변수 전달


84

같은 매개 변수가 있다고 가정 해 봅시다 limit. 이것은 모든 곳에서 사용되며 업데이트해야 할 경우 모든 곳에서 변경해야하는 고통입니다.

parameters:
    - name: limit
      in: query
      description: Limits the number of returned results
      required: false
      type: number
      format: int32

$ ref를 사용하여 다른 곳에서 정의하고 재사용 할 수 있습니까? 나는 우연히 이 티켓 누군가가 변경하거나 기능을 개선하고자하는 것을 제안하지만, 오늘 이미 존재하거나하지 않을 경우 내가 말할 수 없다?

답변:


132

이 기능은 Swagger 2.0에 이미 있습니다. 링크 된 티켓은이 기능의 기능에 영향을 미치지 않는 특정 메커니즘에 대해 설명합니다.

최상위 객체 (Swagger 객체라고 함)에는 parameters재사용 가능한 매개 변수를 정의 할 수 있는 속성이 있습니다. 매개 변수에 이름을 지정하고 경로 / 특정 작업에서 참조 할 수 있습니다. 최상위 수준 매개 변수는 정의 일 뿐이며 사양의 모든 작업에 자동으로 적용되지는 않습니다.

여기 ( https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/reusableParameters.json) 에서 이에 대한 예제를 찾을 수 있습니다 .

귀하의 경우 다음을 수행하고 싶습니다.

# define a path with parameter reference
/path:
   get:
      parameters:
         - $ref: "#/parameters/limitParam"
         - $ref: "#/parameters/offsetParam"

# define reusable parameters:
parameters:
   limitParam:
      name: limit
      in: query
      description: Limits the number of returned results
      required: false
      type: integer
      format: int32
   offsetParam:
      name: offset
      in: query
      description: Offset from which start returned results
      required: false
      type: integer
      format: int32

경로 매개 변수로도이 작업을 수행 할 수 있습니까? 아니면 쿼리 매개 변수 만?
brandonscript

매개 변수가 사용되는 모든 매개 변수 유형 (경로 수준 또는 작업 자체에서) 최상위 수준 매개 변수 정의는 작업에 대해 명시 적으로 정의 된 것과 동일한 매개 변수 개체를 사용합니다.
Ron

6
매개 변수를 확장 할 수 있습니까? 예를 들어, 동일한 매개 변수 정의가 in: path한 경우와 in: query다른 경우에 있을 수 있습니다 . 또한 한 경우에는 선택 사항이고 다른 경우에는 필수 일 수 있습니다.

8
이에 대해 두 개의 별도 정의를 만들어야합니다.
Ron

1
전체 요청 인수를 재사용 할 수 있습니까? ie .: parameters : $ ref : "# / parameters / requestParams"
Konrad Gałęzowski

28

완성도를 위해 OpenAPI (일명 swagger v3) 에서 다음과 같이 표시됩니다 .

openapi: "3.0.0"
servers:
    - url: /v1
      description: local server

paths:
   /path:
      get:
         parameters:
            - $ref: "#/components/parameters/limitParam"

components:
   parameters:
      limitParam:
         name: limit
         in: query
         description: Limits the number of returned results
         required: false
         schema:
            type: integer
            minimum: 10
            default: 10
            multipleOf: 10 # matches 10, 20, ...
            format: int32
당사 사이트를 사용함과 동시에 당사의 쿠키 정책개인정보 보호정책을 읽고 이해하였음을 인정하는 것으로 간주합니다.
Licensed under cc by-sa 3.0 with attribution required.