स्वैगर

Question

में भूमिका/अनुमति सुरक्षा को परिभाषित करने के लिए कैसे करें मेरे एपीआई दस्तावेज़ में, मैं प्रत्येक एपीआई एंडपॉइंट के लिए आवश्यक सुरक्षा को परिभाषित करना चाहता हूं। इस परियोजना ने भूमिकाओं और अनुमतियों को परिभाषित किया है जो यह निर्धारित करते हैं कि कौन से उपयोगकर्ता एपीआई एक्सेस कर सकते हैं। इस जानकारी को दस्तावेज करने के लिए स्वैगर में सबसे अच्छा तरीका क्या है? क्या इस विवरण को दिखाने के लिए कोई सर्वोत्तम अभ्यास या सिफारिश है?

यह मैंने सुरक्षा परिभाषाओं और भूमिकाओं के लिए स्वयं परिभाषित चर का उपयोग करके कोशिश की, लेकिन जब मैं इसे swagger2markup के माध्यम से चलाता हूं या swagger- के माध्यम से उस जानकारी (x-role-names) को प्रलेखन में कॉपी नहीं किया गया है, ui।

"securityDefinitions": { 
    "baseUserSecurity": { 
      "type": "basic", 
      "x-role-names": "test" 
     } 
    } 

endpoint प्रति भूमिका और अनुमति जानकारी दस्तावेज़ के लिए सबसे अच्छा तरीका क्या है?

Answer 1

यदि आपका एपीआई ओथ प्रमाणीकरण का उपयोग करता है, तो आप इसके लिए स्कोप का उपयोग कर सकते हैं। बुनियादी प्रमाणीकरण के खिलाफ स्वैगर/OpenApi में भूमिकाओं का प्रतिनिधित्व करने के लिए कोई मानक तरीका नहीं है, तो आप (, जैसा कि आप मिल गया है जो इस तरह के स्वैगर-यूआई या swagger2markup के रूप में उपकरणों की व्याख्या का कोई तरीका नहीं) सहित विक्रेता-एक्सटेंशन का उपयोग कर छोड़ दिया जाता है, या summary या description गुणों में टेक्स्ट के रूप में जानकारी।

आप securityDefinitions सभी प्रकार basic को परिभाषित कर सकते हैं और प्रति भूमिका एक का उपयोग कर सकते हैं लेकिन यह एक हैक का थोड़ा सा है।

भी एक प्रस्ताव अन्य सुरक्षा योजनाओं के लिए स्कोप के उपयोग को चौड़ा करने के लिए इस मुद्दे को https://github.com/OAI/OpenAPI-Specification/issues/1366 देखें।