Swagger: haritası <dize, Nesne>

Question

Ben Swagger string anahtarlarıyla endeksli giriş ve çıkış, nesnelerin haritalar, hem kullanan bir API belgelemek gerekir

.

Örnek:

{ 
    "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" ve "çubuk" herhangi bir dize tuşları olabilir, ama bunlar tuşlarının set arasında benzersiz olmalıdır.

Ben Swagger, ben nesneleri dizisi tanımlayabilirsiniz, biliyorum, ama biz o zaman bir şey olurdu çünkü bu farklı bir API verir: Ben 'Open API Specification' - 'Add support for Map data types #38' sayfasını okudum

{ 
    "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" 
     } 
    ] 
} 

. Anladığım kadarıyla, ekProperties kullanılmasını önerir, ancak benim ihtiyacım (veya kullandığım Swagger UI 2.1.4 ile çalışmıyor) yanıt vermiyor gibi görünüyor. Bir şey mi özledim?

buldum Şimdiye kadar aşağıdaki iş çevresinde (Swagger JSON cinsinden):

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 
       } 
      } 
     } 
    } 
} 

Bu neredeyse iş yapar, ancak okuyucu herhangi bir dize "anahtar" olabileceğini anlamak zorundadır ve birkaç kez tekrarlanabilir.

ihtiyacım olanı başarmak için daha iyi bir yolu var mı?

Answer 1

additionalProperties kullanımı, sprinkleri OpenAPI (fka. Swagger) ile tanımlamak için uygun yoldur, ancak Swagger UI bunları şimdilik oluşturmaz.

sorun, haritanın nesnelerin aynı tipte (aşağıdaki örnekte default) olmayan bir gerekli özellik tanımlamak bu hile kullanmak açıklamalarını dahil bazı ipucu verebilir arada burada https://github.com/swagger-api/swagger-ui/issues/1248

izlenir:

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' 

Bu açıklama API sözleşmesini değiştirmez ve belgeleri iyileştirmez. Ben doğru anlamak

Answer 2

, temel problem anahtar bir dize daha karmaşıktır, özellikle Java Kart evrensel olarak kabul edilmiş JSON haritalama olmasıdır. GSON'un bir yaklaşımı (anahtarı bir nesne olarak ele alır) alırken, Jackson'ın bir tane daha aldığını (bir dizginin anahtarını serileştirdiğini) gördüm. Bir Haritaya eşdeğer bir eşdeğeri (bir Sözlük) üçüncü bir yaklaşım kullanır (her girişi "Anahtar" ve "Değer" olarak adlandırılan özellikler ile kendi başına bir anahtar-değer nesnesi olarak ele alır). Swagger, dil ve serileştirici için agnostik olmaya çalıştığında, bu onu imkansız bir duruma sokar.