स्वैगर / ओपनएपीआई - पुन: प्रयोज्य परिभाषित पैरामीटर को पारित करने के लिए $ रेफ का उपयोग करें

Question

मान लीजिए कि मुझे एक पैरामीटर मिला है जैसे limit। यदि इसे अद्यतन करने की आवश्यकता है तो इसे हर जगह उपयोग किया जाता है और इसे हर जगह बदलना पड़ता है:

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

क्या मैं कहीं और इसे परिभाषित करने और इसे पुन: प्रयोज्य बनाने के लिए $ रेफ का उपयोग कर सकता हूं? मैं इस टिकट पर आया था जो बताता है कि कोई व्यक्ति फीचर को बदलना या सुधारना चाहता है, लेकिन मैं यह नहीं बता सकता कि यह पहले से मौजूद है या नहीं?

Answer 1

यह सुविधा पहले से ही Swagger 2.0 में मौजूद है। लिंक्ड टिकट इसके बारे में कुछ विशिष्ट यांत्रिकी के बारे में बात करता है जो इस सुविधा की कार्यक्षमता को प्रभावित नहीं करता है।

शीर्ष स्तर की वस्तु (स्वैगर ऑब्जेक्ट के रूप में संदर्भित) में, एक ऐसी 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

Comments

क्या आप पथ मापदंडों के साथ भी ऐसा कर सकते हैं? या केवल क्वेरी पैरामीटर?

— ब्रैंडनस्क्रिप्ट

कोई भी पैरामीटर प्रकार, जहां भी पैरामीटर का उपयोग किया जाता है (पथ स्तर पर या ऑपरेशन स्वयं)। शीर्ष-स्तरीय पैरामीटर परिभाषा समान पैरामीटर ऑब्जेक्ट का उपयोग करती है क्योंकि ऑपरेशन के लिए स्पष्ट रूप से परिभाषित किया गया है।

— रॉन

क्या एक पैरामीटर का विस्तार करना संभव है? उदाहरण के लिए, एक ही पैरामीटर परिभाषा in: pathएक मामले में और in: queryदूसरे में हो सकती है । इसके अलावा एक मामले में वैकल्पिक और दूसरे में आवश्यक हो सकता है।

आपको इसके लिए दो अलग-अलग परिभाषाएँ बनानी होंगी।

— रॉन

क्या पूरे अनुरोध तर्कों को पुन: प्रयोज्य बनाना संभव है? यानी: पैरामीटर: $ रेफ: "# / पैरामीटर / रिक्वेस्टपराम"

— कोनराड गालोज़ोव्स्की

Answer 2

पूर्णता के लिए, यहाँ OpenAPI (उर्फ स्वैगर 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