स्प्रिंग हेटोआस (swagger के साथ) से दस्तावेज़ एचएएल "_links"?

Question

मेरे पास एक आरईएसटी सेवा है जो मैं अपने क्लाइंट डेवलपमेंट टीम के लिए दस्तावेज करना चाहता हूं।

तो मैं अपने संसाधनों एपीआई के Spring-Hateoas से कुछ Links जोड़ा, और यह swagger-springmvc@Api... एनोटेशन में प्लग सब कुछ दस्तावेज़ और एक अच्छा API संदर्भ बनाने के मेरे कोणीय टीम मेरी बाकी सेवा को समझने में सक्षम होने के लिए करने के लिए।

समस्या यह है कि swagger यह पता लगाने में असमर्थ है कि कौन से लिंक संभव हैं, और बस मुझे अपने संभावित मूल्यों के बिना Links का एक बड़ा सरणी दें।

यहां एक (सरल) उदाहरण है। अकड़ का पता लगाता है:

Model Schema 
CollectionListResource { 
    collections (array[CollectionResource]): All available collections, 
    links (array[Link]): Relations for next actions 
} 
CollectionResource { 
    collectionId (string): Collection Unique Id, 
    name (string): Human readable collection name, 
    links (array[Link]): Relations for next actions 
} 
Link { 
    rel (string, optional), 
    templated (boolean, optional), 
    href (string, optional) 
} 

और मैं एचएएल में वास्तव में मिलती है:

{"collections": 
    [{"collectionId":"5370a206b399c65f05a7c59e", 
     "name":"default", 
     "_links":{ [ 
      "self":{ 
       "href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e" 
      }, 

      "delete":{ 
       "href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e" 
      } 
     ]} 
     }, ...]} 

मैं Link का विस्तार करने की कोशिश की है और ResourceSupport उनमें से संस्करण annoted की है, लेकिन यह मेरे लिए कहीं ले जाते हैं।

क्या कोई तरीका/उपकरण है जिसका उपयोग मैं एक अच्छा एपीआई दस्तावेज़ उत्पन्न करने के लिए कर सकता हूं जो बताता है कि self संबंध सामग्री प्राप्त करना है, और delete संबंध संग्रह को हटाना है?

मैं अपनी अच्छी यूआई के लिए अकड़ पसंद आया, लेकिन मैं अपने प्रलेखन उपकरण को बदलने अगर इसकी मदद वास्तव में पूरा दस्तावेज़ होने आपत्ति नहीं है।

मैं अंततः एक और लिंक जनरेटर के लिए वसंत-नफरत बदलने के बारे में सोच सकता हूं, लेकिन मुझे यकीन नहीं है कि अभी एक बेहतर टूल उपलब्ध है।

Answer 1

स्वैगर-यूआई hypermedia aware नहीं है; या कम से कम इसकी सीमित है कि यह केवल शीर्ष स्तर एपीआई से एपीआई लिस्टिंग में नेविगेट कर सकता है। बैंड प्रलेखन के बाहर बाहरी दस्तावेजों को जोड़ने के उल्लेखनीय जोड़े के साथ, या तो spec के v2.0 में यह बहुत कुछ नहीं बदला है।

आपको क्या चाहिए HAL browser और swagger-ui का एक संकर है। जैसा कि आपने सही तरीके से बताया है, "हटाएं" शब्द और संग्रह संसाधन के संदर्भ में इसका क्या अर्थ है, के बीच एक अर्थपूर्ण अंतर है। एचएएल इस अंतर को पुल करने के लिए करी के संयोजन और वैकल्पिक रूप से एक प्रोफाइल दस्तावेज़ ALPS का उपयोग करता है। Curies लिंक किए गए संबंधों के नामित संस्करणों के अलावा कुछ भी नहीं है ताकि वे अन्य डोमेन के साथ टकराव न करें। Restful Web APIs इन विचारों और मीडिया प्रकारों को डिज़ाइन करने के तरीके के बारे में अधिक जानने के लिए एक महान संसाधन है। spring data rest project में यह भी प्राप्त करने का एक अच्छा उदाहरण है कि इसे कैसे प्राप्त किया जाए।

• तरीके कि मुझे लगता है कि काम करेगा में से एक संचालन उन्मुख एपीआई देखने के बजाय उन्मुख देखने के लिए, समय सीमा है कि आप संभवतः के साथ काम कर रहे हैं में नहीं वास्तव में संभव सूचीकरण का समर्थन करने के लिए swagger specification समायोजित करने के लिए है।
• मौजूदा आरएफसी की तरह rfc5023 का उपयोग संसाधन संसाधनों के "संपादन" के बारे में साझा समझने के लिए करें।
• आखिरकार यदि मानक लिंक संबंधों में से कोई भी कार्रवाई के इरादे को व्यक्त नहीं करता है, तो अपने स्वयं के एप्लिकेशन विशिष्ट अर्थशास्त्र को परिभाषित करें जो इन अनुप्रयोगों के विशिष्ट लिंक संबंधों के लिए दस्तावेज प्रदान करते हैं। इस तरह आपकी सेवा के ग्राहकों को आपके आवेदन के संदर्भ में इन संबंधों की साझा समझ होगी।

नीचे एक उदाहरण है कि यह दर्शाता है और इन तरीकों को जोड़ती है।

{"collections": 
[{"collectionId":"5370a206b399c65f05a7c59e", 
    "name":"default", 
    "curies": [ 
     { 
      "name": "sw", 
      "href": "http://swagger.io/rels/{rel}", 
      "templated": true 
     }, 
     { 
      "name": "iana", 
      "href": "http://tools.ietf.org/html/rfc5023", 
      "templated": false 
     }, 
     { 
      "name": "col", 
      "href": "http://localhost:9080/collections/{rel}", 
      "templated": false 
     } 
    ], 
    "_links":{ [ 
     "self":{ 
      "href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e" 
     }, 
     "sw:operation":{ 
      "href":"http://localhost:9080/api-docs/collections#delete" 
     }, 
     "sw:operation":{ 
      "href":"http://localhost:9080/api-docs/collections#search" 
     }, 
     "sw:operation":{ 
      "href":"http://localhost:9080/api-docs/collections#update" 
     }, 
     "iana:edit":{ 
      "href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e" 
     }, 
     "col:delete": { 
      "href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e" 
     } 
    ]} 
    }, ...]} 

तो सबसे विशिष्ट करने के लिए सबसे सामान्य से, समाधान (इसी क्रम में)

• IANA योग्य लिंक "संपादित करें" इस मामले में, एक विशेष अर्थ है एक बहुत ही विशेष अर्थ नहीं है कि हर विश्राम ग्राहक लागू कर सकते हैं। यह एक जनरेटेड लिंक प्रकार है।
• स्व-योग्य लिंक संबंधों का एक विशेष अर्थ भी है, इसका अर्थ यह है कि swagger api दस्तावेज़ीकरण में संचालन के लिए href गहरे लिंक का तात्पर्य है।
• कॉल योग्य लिंक एप्लिकेशन विशिष्ट लिंक हैं जो केवल आपके एप्लिकेशन के बारे में जानते हैं।

मुझे पता है कि यह आपके प्रश्न का सटीक उत्तर नहीं देता है, और इस स्थान के उपकरण अभी भी विकसित हो रहे हैं। उम्मीद है की यह मदद करेगा।

अस्वीकरण: मैं में से springfox में से एक हूं जो वसंत एकीकरण समाधान है जो स्वैगर सेवा विवरण प्रदान करना आसान बनाता है। तो इस समस्या को हल करने के लिए आप इसे कैसे पसंद करेंगे इस पर कोई प्रतिक्रिया बहुत स्वागत है!