dictionary - Swagger: mapa de<string, Object>

Question

Necesito documentar con Swagger una API que utiliza, tanto como entrada como salida, mapas de objetos, indexados por teclas de cadena.

Ejemplo:

{
    "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" y "bar" pueden ser cualquier tecla de cadena, pero deben ser únicos entre el conjunto de teclas.

Sé que, con Swagger, puedo definir una matriz de objetos, pero esto da una API diferente ya que entonces tendríamos algo como:

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

He leído la página ''Especificación de API abierta'' - ''Agregar soporte para tipos de datos de mapa # 38'' . Por lo que entiendo, recomienda usar propiedades adicionales, pero no parece responder a mi necesidad (o no funciona con Swagger UI 2.1.4 que uso). ¿Me he perdido algo?

Hasta ahora he encontrado la siguiente solución (en Swagger 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
                }
            }
        }
    }
}

Esto casi hace el trabajo, pero el lector tiene que entender que "clave" puede ser cualquier cadena y puede repetirse varias veces.

¿Hay una mejor manera de lograr lo que necesito?

Answer 1

El uso de propiedades additionalProperties es la forma correcta de describir hashamp con la especificación OpenAPI (fka. Swagger), pero la interfaz de usuario de Swagger no las representa por el momento.

El problema se rastrea aquí https://github.com/swagger-api/swagger-ui/issues/1248

Mientras tanto, puede usar este truco para definir una propiedad no requerida ( default en el ejemplo a continuación) del mismo tipo de objetos del mapa y dar alguna pista dentro de la descripción:

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

Esta descripción no modifica el contrato de API y mejora la documentación.

Answer 2

Si lo entiendo correctamente, el problema básico es que no existe una asignación JSON universalmente aceptada para un Mapa Java, especialmente cuando la clave es más compleja que una cadena. He visto que GSON adopta un enfoque (trata la clave como un objeto), mientras que Jackson adopta otro (serializa la clave en una cadena). El c # equivalente a un Mapa (un Diccionario) usa un tercer enfoque (tratando cada entrada como un objeto clave-valor por derecho propio con propiedades llamadas "Clave" y "Valor"). Como Swagger intenta ser agnóstico al lenguaje y al serializador, esto lo coloca en una posición imposible.