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.