2016-03-21 32 views
8

का नक्शा मुझे स्वैगर एपीआई के साथ दस्तावेज़ करने की आवश्यकता है जो इनपुट और आउटपुट, ऑब्जेक्ट्स के मानचित्र, स्ट्रिंग कुंजियों द्वारा अनुक्रमित दोनों के रूप में उपयोग करता है।स्वैगर: <स्ट्रिंग, ऑब्जेक्ट>

उदाहरण:

{ 
    "a_property": { 
     "foo": { 
      "property_1": "a string 1", 
      "property_2": "a string 2" 
     }, 
     "bar": { 
      "property_1": "a string 3", 
      "property_2": "a string 4" 
     } 
    } 
} 

"foo" और "बार" कोई भी स्ट्रिंग कुंजी हो सकता है, लेकिन वे कुंजियों का सेट के बीच में अद्वितीय होना चाहिए।

मुझे पता है कि, अकड़ कर चलने वाले, मैं वस्तुओं की एक सरणी परिभाषित कर सकते हैं, लेकिन जब से हम तो कुछ के रूप में होता है यह एक अलग एपीआई देता है:

{ 
    "a_property": [ 
     { 
      "key": "foo" 
      "property_1": "a string 1", 
      "property_2": "a string 2" 
     }, 
     { 
      "key": "bar" 
      "property_1": "a string 3", 
      "property_2": "a string 4" 
     } 
    ] 
} 

मैं 'Open API Specification' - 'Add support for Map data types #38' पेज पढ़ लिया है। जहां तक ​​मैं समझता हूं, यह अतिरिक्त प्रॉपर्टीज का उपयोग करने की अनुशंसा करता है, लेकिन ऐसा लगता है कि मेरी आवश्यकता (या यह मैं उपयोग करने वाले स्वैगर यूआई 2.1.4 के साथ काम नहीं करता)। क्या मुझे कुछ याद आया?

अब तक मैं पाया है निम्नलिखित काम के आसपास (स्वैगर JSON में):

a_property: { 
    description: "This is a map that can contain several objects indexed by different keys.", 
    type: object, 
    properties: { 
     key: { 
      description: "map item", 
      type: "object", 
      properties: { 
       property_1: { 
        description: "first property", 
        type: string 
       }, 
       property_2: { 
        description: "second property", 
        type: string 
       } 
      } 
     } 
    } 
} 

यह लगभग, काम करता है, लेकिन पाठक को समझने के लिए कि "कुंजी" कोई भी स्ट्रिंग हो सकता है और कई बार दोहराया जा सकता है।

क्या मुझे आवश्यकतानुसार हासिल करने का एक बेहतर तरीका है?

+1

व्यक्तिगत रूप से मुझे समझने में कुछ समय लगा * क्यों * 'अतिरिक्त प्रॉपर्टीज सही जवाब है: http://stackoverflow.com/a/41240118/110488 –

उत्तर

21

additionalProperties का उपयोग ओपनएपीआई (एफका। स्वैगर) विशिष्टता के साथ हैशैम्प का वर्णन करने का सही तरीका है, लेकिन स्वैगर यूआई अब उन्हें प्रस्तुत नहीं करता है।

यहां मुद्दा यह है https://github.com/swagger-api/swagger-ui/issues/1248

ट्रैक किया जाता है इस बीच आप नक्शे के वस्तुओं की एक ही प्रकार के (नीचे उदाहरण में default) एक गैर आवश्यक संपत्ति को परिभाषित इस चाल का उपयोग करें और वर्णन के भीतर कुछ संकेत दे सकते हैं:

swagger: "2.0" 
info: 
    version: 1.0.0 
    title: Hashmap 

paths: {} 

definitions: 
    MapItem: 
    properties: 
     firstname: 
     type: string 
     lastname: 
     type: string 
    Map: 
    description: a (key, MapItem) map. `default`is an example key 
    properties: 
     default: 
     $ref: '#/definitions/MapItem' 
    additionalProperties: 
     $ref: '#/definitions/MapItem' 

यह विवरण एपीआई अनुबंध को संशोधित नहीं करता है और दस्तावेज़ीकरण में सुधार नहीं करता है।

+0

SwaggerUI में संबंधित समस्या का संदर्भ खोजने के लिए धन्यवाद। दुर्भाग्यवश मेरे पास आपके उत्तर को वोट देने के लिए अभी तक पर्याप्त प्रतिष्ठा नहीं है ;-) –

+0

इस तिथि के अनुसार, कम से कम स्वैगर-कोडेजन का जावास्क्रिप्ट संस्करण अतिरिक्त गुणों को अनदेखा करता है, इसलिए यह कुछ के लिए एक शोस्टॉप हो सकता है –

2

यदि मैं इसे सही ढंग से समझता हूं, तो मूल समस्या यह है कि जावा मानचित्र के लिए कोई सार्वभौमिक रूप से स्वीकृत JSON मैपिंग नहीं है, खासकर जब कुंजी स्ट्रिंग से अधिक जटिल होती है। मैंने देखा है कि जीएसओएन एक दृष्टिकोण लेता है (एक वस्तु के रूप में कुंजी का इलाज), जबकि जैक्सन एक और लेता है (एक स्ट्रिंग के लिए कुंजी serialise)। सी # समकक्ष मानचित्र (एक शब्दकोश) एक तीसरे दृष्टिकोण का उपयोग करता है (प्रत्येक प्रविष्टि को कुंजी-मूल्य वस्तु के रूप में अपने आप में "कुंजी" और "मान" नामक गुणों के साथ व्यवहार करता है)। जैसे स्वैगर भाषा और धारावाहिक के लिए अज्ञेयवादी होने की कोशिश करता है, यह इसे एक असंभव स्थिति में डाल देता है।

संबंधित मुद्दे