वैश्विक मानकों को परिभाषित करें

Question

मैं अपने एपीआई दस्तावेज को प्रति हाथ करके और ऑटो जनरेट नहीं कर रहा हूं। वहां मेरे पास हेडर हैं जिन्हें सभी एपीआई में भेजा जाना चाहिए और यह नहीं पता कि पूरे एपीआई के लिए विश्व स्तर पर पैरामीटर को परिभाषित करना संभव है या नहीं?

इनमें से कुछ शीर्षलेख स्थिर हैं और कुछ को एपीआई पर कॉल करते समय सेट किया जाना है, लेकिन वे सभी एपीआई में समान हैं, मैं प्रत्येक एपीआई और प्रत्येक विधि के लिए पैरामीटर कॉपी और पेस्ट नहीं करना चाहता भविष्य में बनाए रखने योग्य नहीं है।

मैंने एपीआई परिभाषा द्वारा स्थैतिक शीर्षलेख देखा लेकिन कोई भी दस्तावेज़ नहीं है कि कोई उन्हें कैसे सेट कर सकता है या उनका उपयोग कर सकता है।

क्या यह संभव है या नहीं?

Answer 1

प्रति this Swagger issue comment के रूप में, वैश्विक मानकों (शीर्ष लेख पैरामीटर सहित) के लिए समर्थन निकट भविष्य में की योजना बनाई नहीं है, लेकिन पुनरावृत्ति आप @Arnaud's जवाब (parameters: - $ref: '#/parameters/paramX') में के रूप में मानकों के संदर्भ का उपयोग करना चाहिए सीमित करने के लिए।

Answer 2

जब एपीआई बुला उपभोक्ता द्वारा भेजे गए हेडर मापदंडों के बारे में अपनी बात करते हैं:

आपको कम से कम उन्हें मापदंडों वर्गों में एक बार और सभी के लिए परिभाषित कर सकते हैं उसके बाद ही उन्हें संदर्भ जब जरूरत। नीचे दिए गए उदाहरण में:

• CommonPathParameterHeader, ReusableParameterHeader और AnotherReusableParameterHeader दस्तावेज़ की जड़ पर parameters में एक बार और सभी के लिए परिभाषित कर रहे हैं और किसी भी पैरामीटर सूची
• CommonPathParameterHeader/resources की parameters खंड में संदर्भित है में इस्तेमाल किया जा सकता और /other-resources पथ, जिसका अर्थ है कि इन पथों के सभी संचालन को इस हेडर की आवश्यकता है
• ReusableParameterHeaderget /resources में संदर्भित है जिसका अर्थ है कि इस ऑपरेशन पर इसकी आवश्यकता है
में get /other-resources

उदाहरण AnotherReusableParameterHeader के लिए

यही बात:

swagger: '2.0' 
info: 
    version: 1.0.0 
    title: Header API 
    description: A simple API to learn how you can define headers 

parameters: 
    CommonPathParameterHeader: 
    name: COMMON-PARAMETER-HEADER 
    type: string 
    in: header 
    required: true 
    ReusableParameterHeader: 
    name: REUSABLE-PARAMETER-HEADER 
    type: string 
    in: header 
    required: true 
    AnotherReusableParameterHeader: 
    name: ANOTHER-REUSABLE-PARAMETER-HEADER 
    type: string 
    in: header 
    required: true 

paths: 
    /resources: 
    parameters: 
     - $ref: '#/parameters/CommonPathParameterHeader' 
    get: 
     parameters: 
     - $ref: '#/parameters/ReusableParameterHeader' 
     responses: 
     '200': 
      description: gets some resources 
    /other-resources: 
    parameters: 
     - $ref: '#/parameters/CommonPathParameterHeader' 
    get: 
     parameters: 
     - $ref: '#/parameters/AnotherReusableParameterHeader' 
     responses: 
     '200': 
      description: gets some other resources 
    post: 
     responses: 
     '204': 
      description: Succesfully created. 

हैडर के बारे में अपनी बात प्रत्येक एपीआई प्रतिक्रिया दुर्भाग्य से आप नहीं पुन: प्रयोज्य प्रतिक्रिया हेडर को परिभाषित करता है सकते हैं के साथ भेजा है। लेकिन कम से कम आप उदाहरण के लिए 500 जैसे सामान्य प्रतिक्रिया के लिए इन शीर्षकों वाले पुन: प्रयोज्य प्रतिक्रिया को परिभाषित कर सकते हैं।

उदाहरण:

swagger: '2.0' 
info: 
    version: 1.0.0 
    title: Header API 
    description: A simple API to learn how you can define headers 

parameters: 
    CommonPathParameterHeader: 
    name: COMMON-PARAMETER-HEADER 
    type: string 
    in: header 
    required: true 
    ReusableParameterHeader: 
    name: REUSABLE-PARAMETER-HEADER 
    type: string 
    in: header 
    required: true 
    AnotherReusableParameterHeader: 
    name: ANOTHER-REUSABLE-PARAMETER-HEADER 
    type: string 
    in: header 
    required: true 

paths: 
    /resources: 
    parameters: 
     - $ref: '#/parameters/CommonPathParameterHeader' 
    get: 
     parameters: 
     - $ref: '#/parameters/ReusableParameterHeader' 
     responses: 
     '200': 
      description: gets some resources 
      headers: 
      X-Rate-Limit-Remaining: 
       type: integer 
      X-Rate-Limit-Reset: 
       type: string 
       format: date-time 
    /other-resources: 
    parameters: 
     - $ref: '#/parameters/CommonPathParameterHeader' 
    get: 
     parameters: 
     - $ref: '#/parameters/AnotherReusableParameterHeader' 
     responses: 
     '200': 
      description: gets some other resources 
      headers: 
      X-Rate-Limit-Remaining: 
       type: integer 
      X-Rate-Limit-Reset: 
       type: string 
       format: date-time 
    post: 
     responses: 
     '204': 
      description: Succesfully created. 
      headers: 
      X-Rate-Limit-Remaining: 
       type: integer 
      X-Rate-Limit-Reset: 
       type: string 
       format: date-time 
     '500': 
      $ref: '#/responses/Standard500ErrorResponse' 

responses: 
    Standard500ErrorResponse: 
    description: An unexpected error occured. 
    headers: 
     X-Rate-Limit-Remaining: 
     type: integer 
     X-Rate-Limit-Reset: 
     type: string 
     format: date-time 

OpenAPI (fka स्वैगर।) अगला संस्करण के बारे में

OpenAPI कल्पना (fka स्वैगर।) विकसित और (अन्य बातों के अलावा पुन: प्रयोज्य प्रतिक्रिया हेडर की परिभाषा में शामिल होंगे सीएफ https://github.com/OAI/OpenAPI-Specification/issues/563)।