json api swagger-2.0

Swagger 2.0: qué esquema aceptar cualquier valor JSON(complejo)



api swagger-2.0 (2)

La API para la que estoy escribiendo una especificación Swagger 2.0 es básicamente una tienda para cualquier valor JSON.

Quiero una ruta para leer el valor y una ruta para almacenar cualquier valor JSON (nulo, número, entero, cadena, objeto, matriz) de profundidad no predefinida.

Desafortunadamente, parece que Swagger 2.0 es bastante estricto en los esquemas de entrada y salida y no permite todo el conjunto de esquemas permitidos por el esquema JSON. El editor Swagger no permite, por ejemplo, valores mixtos (por ejemplo, una propiedad que puede ser booleana o entera) o matrices poco definidas (el tipo de elementos debe estar estrictamente definido) y objetos.

Así que estoy intentando una solución definiendo un esquema MixedValue :

--- swagger: ''2.0'' info: version: 0.0.1 title: Data store API consumes: - application/json produces: - application/json paths: /attributes/{attrId}/value: parameters: - name: attrId in: path type: string required: true get: responses: ''200'': description: Successful. schema: $ref: ''#/definitions/MixedValue'' put: parameters: - name: value in: body required: true schema: $ref: ''#/definitions/MixedValue'' responses: responses: ''201'': description: Successful. definitions: MixedValue: type: object properties: type: type: string enum: - ''null'' - boolean - number - integer - string - object - array boolean: type: boolean number: type: number integer: type: integer string: type: string object: description: deep JSON object type: object additionalProperties: true array: description: deep JSON array type: array required: - type

Pero el Editor Swagger rechaza las propiedades de object y array poco definidas.

Preguntas: - ¿Hay alguna forma de solucionar este problema? - ¿Es solo un error del Editor Swagger o un límite fuerte de la especificación Swagger 2.0? - ¿Hay una mejor manera (mejor práctica) para especificar lo que necesito? - ¿Puedo esperar algunas limitaciones en el código producido por swagger para algunos idiomas con mi especificación API?


Tal vez esto es lo que buscas "Objetos con dibujos":

Patrón de campo: ^ x-

Tipo: Cualquiera

Descripción: permite extensiones al esquema Swagger. El nombre del campo DEBE comenzar con x-, por ejemplo, x-internal-id. El valor puede ser nulo, primitivo, una matriz o un objeto. Ver Extensiones de proveedores para más detalles.

Fuente: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md


Un esquema de tipo arbitrario se puede definir así:

definitions: AnyValue: {}

o si quieres una description :

definitions: AnyValue: description: ''Can be anything: string, number, array, object, etc.''

Sin un type definido, AnyValue puede ser cualquier cosa: cadena, número, booleano, matriz, objeto, etc. Consulte estas preguntas y respuestas para obtener más detalles sobre cómo funcionan los esquemas sin type .

En OpenAPI 3.0 puede agregar nullable: true para permitir el valor null :

components: schemas: AnyValue: nullable: true description: Can be anything, including null.


Así es como Swagger Editor 2.0 maneja un parámetro de cuerpo con el esquema AnyValue :

Sin embargo, no sé cómo los generadores de código manejan esto.