I am using OpenApi 3.0 and I have encountered a requirement with enum with some extra fields.
Example:
enum:
- name: a
x-field-uid: 1
description: some description
- name: b
x-field-uid: 2
description: some description
- name: c
x-field-uid: 3
description: some description
Though I did not find anything similar pattern from the openapi spec, but I tried using the above format for enums and openapi spec validation doesn't through any error.
I wonder if this can be used or not.
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'd like to provide a series of custom codes and message for my error 400 but can't find any way to do so.
Ideally something like:
Error:
type: object
enum:
- [E01, 'Error1']
- [E02, 'Error2']
And so on
So I'm not sure that enums here can help you.
If you take a look over official documentation Enums are just strings, not object https://swagger.io/docs/specification/data-models/enums/ .
So my proposal is to use :
ErrorType:
type: object
properties:
code:
type: integer
name:
type: string
example: # Sample object
code: 10
name: Custom Error
Error:
type: object
properties:
errors:
oneOf:
- $ref '#/ErrorType'
- etc...
or directly without properties
Error:
type: object
oneOf:
- $ref '#/ErrorType'
- etc...
You can take a look for more examples on the official page https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/
You can check out how Twitter has described it with $oneOf ( https://api.twitter.com/labs/2/openapi.json ) but unfortunately this convention is not easy nor supported by code generation tools like openapi-generator.
Until OpenApi supports enum descriptions (proposal is pending), one of the easiest ways are to:
define enum with all possible error codes
in the top level description: section of the spec define an inner section (with markdown notation #Error codes) that lists all error codes along with description.
Automated tool should check if the enum and description is consistent.
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.
I'm trying to specify my API data types in swagger 2.0 using yaml, but I'm getting a reference error (see error details at the bottom).
I'm using a nested structure, where the parent object (InvoiceConfigData) contains an array of child objects (ProviderVariantsData). This is the hierarchy of yaml files:
.api/swagger/cfg/InvoiceConfigData.yaml:
required:
- providerName
- providerVariants
properties:
providerName:
type: string
providerVariants:
type: array
items:
$ref: "#/definitions/ProviderVariantsData"
.api/swagger/cfg/ProviderVariantsData.yaml:
properties:
displayName:
type: string
cif:
type: string
availableTemplates:
type: array
items:
type: string
.api/swagger/definitions.yaml:
ProviderVariantsData:
$ref: ./cfg/ProviderVariantsData.yaml
InvoiceConfigData:
$ref: ./cfg/InvoiceConfigData.yaml
But I get the following errors:
API Errors:
#/definitions/InvoiceConfigData/$ref: Reference could not be resolved: ./cfg/InvoiceConfigData.yaml
#/definitions/ProviderVariantsData/$ref: Reference could not be resolved: ./cfg/ProviderVariantsData.yaml
API Warnings:
#/definitions/ProviderVariantsData: Definition is defined but is not used: #/definitions/ProviderVariantsData
There's something wrong in the way I reference the ProviderVariantsData, but I can't find what's causing the error. I've tried to flip the order in "definitions.yaml" (InvoiceConfigData above ProviderVariansData) without success.
swagger 2.0 doesn't support multiple YAML files.