The API for which I'm writing a Swagger 2.0 specification is basically a store for any JSON value.
I want a path to read value and a path to store any JSON values (null, number, integer, string, object, array) of non-predefined depth.
Unfortunately, it seems that Swagger 2.0 is quite strict on schemas for input and output and does not allow the whole set of schemas allowed by JSON Schema. The Swagger editor doesn't allow for example mixed values (for example a property that can be either a boolean or an integer) or loosely defined arrays (the type of items must be strictly defined) and objects.
So I'm trying a workaround by defining a MixedValue
schema:
---
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
But the Swagger Editor refuses the loosely defined object
and array
properties.
Questions: - Is there a way to workaround this issue? - Is it just a Swagger Editor bug or a strong limit of the Swagger 2.0 spec? - Is there a better way (best practice) to specify what I need? - Can I expect some limitations in code produced by swagger for some languages with my API spec?
An arbitrary-type schema can be defined using an empty schema {}
:
# swagger: '2.0'
definitions:
AnyValue: {}
# openapi: 3.0.0
components:
schemas:
AnyValue: {}
or if you want a description
:
# swagger: '2.0'
definitions:
AnyValue:
description: 'Can be anything: string, number, array, object, etc. (except `null`)'
# openapi: 3.0.0
components:
schemas:
AnyValue:
description: 'Can be anything: string, number, array, object, etc., including `null`'
Without a defined type
, a schema allows any values. Note that OpenAPI 2.0 Specification does not support null
values, but some tools might support nulls nevertheless.
In OpenAPI 3.0, type
-less schemas allow null
values unless nulls are explicitly disallowed by other constraints (such as an enum
).
See this Q&A for more details on how type
-less schemas work.
Here's how Swagger Editor 2.0 handles a body parameter with the AnyValue
schema:
I don't know how code generators handle this though.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With