Swagger / OpenAPI - sử dụng $ ref để chuyển một tham số đã xác định có thể sử dụng lại

Question 1

Giả sử tôi có một tham số như limit. Cái này được sử dụng khắp nơi và thật khó để thay đổi nó ở mọi nơi nếu tôi cần cập nhật nó:

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

Tôi có thể sử dụng $ ref để xác định điều này ở nơi khác và làm cho nó có thể sử dụng lại được không? Tôi đã xem qua tấm vé này gợi ý rằng ai đó muốn thay đổi hoặc cải thiện tính năng, nhưng tôi không thể biết liệu nó đã tồn tại ngày hôm nay hay chưa?

Question 2

Tính năng này đã tồn tại trong Swagger 2.0. Vé được liên kết nói về một số cơ chế cụ thể của nó không ảnh hưởng đến chức năng của tính năng này.

Ở đối tượng cấp cao nhất (được gọi là Đối tượng Swagger), có một thuộc parameterstính nơi bạn có thể xác định các tham số có thể sử dụng lại. Bạn có thể đặt bất kỳ tên nào cho tham số và tham chiếu đến nó từ các đường dẫn / hoạt động cụ thể. Các tham số cấp cao nhất chỉ là định nghĩa và không được áp dụng tự động cho tất cả các hoạt động trong đặc tả.

Bạn có thể tìm thấy một ví dụ cho nó tại đây - https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/reusableParameters.json - ngay cả với một tham số giới hạn.

Trong trường hợp của bạn, bạn muốn làm điều này:

# 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

Question 3

Để hoàn thiện, đây là cách nó trông như thế nào trong OpenAPI (hay còn gọi là 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