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

Program / 글쓴이

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

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

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

답변

이 기능은 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

답변

완성도를 위해 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

답변