Is is possible to set the editability of a field dynamically in openapi 3.0?
The following would be an example of a workaround:
FooBar:
description: |
This type defines a type FooBar.
type: object
properties:
myNumber:
type: EditableNumber
description: The number that should be editable dynamically.
EditableNumber:
description: |
This type defines an editable number.
type: object
properties:
value:
type: number
description: The actual value
editable:
type: boolean
description: whether the field is editable.
required:
- value
But it would be nicer to do something like this:
FooBar:
description: |
This type defines a type FooBar.
type: object
properties:
myNumber:
type: number
description: The number that should be editable dynamically.
readonly: true/false
But true/false can not be set dynamically, right?
Or is there any other possibility to do that without the workaround?
Thanks
Related
I am trying to add multiple examples for an Object property.
The Swagger-Ui and Editor version that I am using are
'{"swaggerEditor":"3.6.31/g10642b3c-dirty","swaggerUi":{"version":"3.23.0","gitRevision":"g23d7260f","gitDirty":true,"buildTimestamp":"Sat, 29 Jun 2019 19:42:59 GMT","machine":"jenins-swagger-oss"}}'
Based on OpenAPI doc, this version of swagger UI and editor have support for multiple examples but I still see this error:
Structural error at components.schemas.MainObject.allOf.3.properties.partitionProperty
should NOT have additional properties
additionalProperty: examples
Jump to line 3016
This is how I have added the examples in the property:
MainObject:
allOf:
- $ref: '#/components/schemas/MainObjectLite'
- type: object
description: foobar.
readOnly: true
required:
- fooRequired
properties:
fooRequired:
type: string
description: system only field used for table data indexing
partitionProperty:
type: string
description: foobar
examples:
sampleExample:
value: 2016-03-04T03:00:00
summary: sample partition
OpenAPI 3.0
Multiple examples are only supported at the media type level and are not supported inside schemas. Schemas and properties can only have a single example, e.g.
partitionProperty:
type: string
example: '2016-03-04T03:00:00'
In other words, this won't work:
MainObject:
type: object
properties:
..
examples: # <--- Won't work
minimal:
summary: Minimal example
value:
foo: bar
full:
summary: Example with all properties
value:
foo: bar
baz: xyzzy
If you want multiple examples, you need to use request examples or response examples instead:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MainObject'
examples:
minimal:
summary: Minimal example
value:
foo: bar
full:
summary: Example with all properties
value:
foo: bar
baz: xyzzy
OpenAPI 3.1
OAS 3.1 uses a newer version of JSON Schema which supports multiple examples in schemas and properties. Unlike media type examples which is a map of named Example Objects, schema-level and property-level examples is a plain list of example values.
MyObject:
type: object
properties:
prop1:
type: string
# Property-level examples
examples:
- foo
- bar
prop2:
type: integer
# Object-level examples
examples:
- prop1: hello
prop2: 5
- prop1: world
prop2: 0
How can I adjust this snippet with oneOf to the equivalent OpenAPI 2.0 version?
formats:
type: array
description: Possible parameter format.
items:
oneOf:
- type: string
- type: object
description: Matched alias formats
properties:
representation:
type: array
description: Alias format representations
items:
type: string
match_multiple:
type: boolean
optional: true
display:
type: string
description: Display string of alias format
In OpenAPI 2.0, the most you can do is to use a typeless schema {} for items, which means the items can be anything except null – numbers, objects, strings, etc. You cannot specify the exact types for items, but you can add an example of an array with different item types.
formats:
type: array
items: {} # <--- means "any type" (except null)
example:
# example of a string item
- test
# example of an object item
- representation: [one, two]
match_multiple: false
display: something
Note: Typeless schema {} can only be used in OAS2 body parameters and response schemas. Path, header and form parameters require a primitive type for array items.
I have a problem with the imports of the generated code of the openapi-generator for Java and Kotlin.
Let's say I have a root.yaml/child1.yaml/child2.yaml with the following content:
components:
schemas:
Transfer:
type: object
allOf:
- $ref: "child1.yaml#/components/schemas/Pet1"
- $ref: "child2.yaml#/components/schemas/Pet2"
child1.yaml:
components:
schemas:
Pet1:
type: object
required:
- id
- name
properties:
id:
type: integer
format: int64
name:
type: string
tag:
type: string
child2.yaml:
components:
schemas:
Pet2:
type: object
required:
- id2
- name2
properties:
id2:
type: integer
format: int64
name2:
type: string
tag2:
type: string
In this case, I do not care for the entities in child1/child2 and I only want the Transfer-object to be build, so I fill the the modelsToGenerate-setting with Transfer only. My problem is that the generated Transfer class always contains imports for the childs, even when they are not needed. For example:
import com.model.Pet1
import com.model.Pet2
data class Transfer (
val id: kotlin.Long,
val name: kotlin.String,
val id2: kotlin.Long,
val name2: kotlin.String,
val tag: kotlin.String? = null,
val tag2: kotlin.String? = null
)
The generated class is not dependend on the childs, but the imports are always generated. Is there a setting or a workaround that I missed? The unnecessary imports also appear when Pet1 and Pet2 are generated, but Transfer is still not dependend on the childs.
My use case is that I do have some very large models in the spec and I would like to split them into multiple files to reduce clutter/duplication without a public class for every single child.
Thanks in advance.
Found the answer myself. You have to run a formatter like Google Java formatter after the classes are generated.
Swagger documentation explains how to define arrays that contain mixed types, such as ["foo", 5, -2, "bar"]. But, how can I define that an array must contain either one type of items (strings, ["foo", "bar"]) or another (integers, [5, -2])?
I've tried this, but Swagger UI can't render it, so I guess that it's wrong:
oneOf:
- items:
- $ref: '#/components/schemas/SchemaA'
- items:
- $ref: '#/components/schemas/SchemaB'
First of all, remember that oneOf is only supported in OpenAPI 3.0 (openapi: 3.0.0) but not in OpenAPI 2.0 (swagger: '2.0').
Your scenario can be defined using oneOf like so:
oneOf:
- type: array
items:
type: string
- type: array
items:
type: integer
- type: array
items:
$ref: '#/components/schemas/SchemaA'
In vanilla JSON Schema, type: array can be moved out of oneOf and placed alongside oneOf but I'm not sure if OpenAPI allows this (the OpenAPI Specification is unclear on this).
type: array
oneOf:
- items:
type: string
- items:
type: integer
- items:
$ref: '#/components/schemas/SchemaA'
I've tried this, but Swagger UI can't render it
Currently, Swagger UI does not automatically generate examples for oneOf and anyOf schemas (see this issue). The workaround is to add an example alongside oneOf manually:
example: [1, 2, 3] # <------
oneOf:
- type: array
items:
type: string
- type: array
items:
type: integer
- type: array
items:
$ref: '#/components/schemas/SchemaA'
Is this possible/correct (shows ok in swagger ui but code gen produces empty classes):
definitions:
name_and_abn:
type: object
properties:
name:
$ref: "#/definitions/entityName"
abn:
$ref: "#/definitions/abn"
abn:
type: string
minLength: 11
maxLength: 11
pattern: "^[0-9]{11}$"
entityName:
type: string
maxLength: 1000
pattern: '^[a-zA-Z][a-zA-Z0-9-_\.]{1,50}$'
If not, is there a way I can reuse field definitions in OpenApi3?
In other words, are objects the only types that can be referenced ($ref) from schema objects?
Thanks