OpenAPI models not being generated when using oneOf - swagger

I am using OpenAPI+OpenAPI-generator with spring boot, and trying to use the schema oneof as follows:
This is the configuration in the requests.yaml file:
...
requestBody:
name: request
required: true
content:
application/json:
schema:
oneOf:
- $ref: 'components.yaml#/Request'
- $ref: 'components.yaml#/ComplexRequest'
...
and this is the relevant configuration in the components.yaml file:
Request:
allOf:
- $ref: '#/BaseInfo'
- type: object
properties:
should_create:
type: boolean
enum: [ false ]
reference_id:
type: string
required:
- reference_id
ComplexRequest:
allOf:
- $ref: '#/BaseInfo'
- type: object
properties:
should_create:
type: boolean
enum: [ true ]
create_data:
$ref: '#/Reference'
required:
- create_data
BaseInfo:
type: object
properties:
customer_id:
type: string
Reference:
type: object
properties:
propery_1:
type: string
propery_2:
type: string
propery_3:
type: string
For some reason, all of these components and only these are not being generated.
Can someone enlighten me on what am I doing wrong here?

If someone is facing this issue, I hope I'll save you some investigation time;
As for March 2022, it seems like oneOf (and anyOf) is just not supported by openapi-generator:
https://openapi-generator.tech/docs/roadmap/#short-term
And though not compatible for my situation, you can try the solutions suggested here:
How to use OpenAPI "oneOf" property with openapi-generator-maven-plugin when generating Spring code

Related

Which is the correct allOf syntax for OpenAPI 3 schema inheritance?

Which syntax is correct - the first one, the second one, or both?
components:
schemas:
FileContent:
allOf:
- $ref: '#/components/schemas/FileInfo'
- type: object
properties:
storageMethod:
$ref: '#/components/schemas/StorageMethod'
contentRange:
type: string
nullable: true
# ... other properties ...
additionalProperties: false
components:
schemas:
FileContent:
type: object
allOf:
- $ref: '#/components/schemas/FileInfo'
properties:
storageMethod:
$ref: '#/components/schemas/StorageMethod'
contentRange:
type: string
nullable: true
# ... other properties ...
additionalProperties: false
In terms of allOf syntax, both versions are correct and technically equivalent:
allOf:
- $ref: '#/components/schemas/Foo'
- properties:
# other properties
# ...
allOf:
- $ref: '#/components/schemas/Foo'
properties:
# other properties
# ...
In OpenAPI 3.1 (which uses JSON Schema 2020-12 by default), there's even no need for allOf if you only have one $ref because $ref now allows sibling keywords. (But you still need allOf to "combine" multiple $refs.)
# openapi: 3.1.0
$ref: '#/components/schemas/Foo'
properties:
# other properties
# ...
The error in your examples is elsewhere - it's the presence of additionalProperties: false. This keyword is problematic because it only knows about its immediate sibling properties and has no visibility into allOf/oneOf/anyOf subschemas or "inherited" schemas. For your examples, this means that properties defined in the FileInfo schema won't actually be allowed in the composed schema.
Here are some more examples to illustrate that additionalProperties: false doesn't work the way one would expect:
allOf:
- $ref: '#/components/schemas/Foo'
- $ref: '#/components/schemas/Bar'
additionalProperties: false
# Expected: Only the properties defined in Foo and Bar are allowed
# Actual: No properties are allowed
allOf:
- $ref: '#/components/schemas/Foo'
- properties:
prop:
type: string
additionalProperties: false
# Expected: The allowed properties are `prop` and those defined in the Foo schema
# Actual: Only the `prop` property is allowed
allOf:
- $ref: '#/components/schemas/Foo'
properties:
prop:
type: string
additionalProperties: false
# Expected: The allowed properties are `prop` and those defined in the Foo schema
# Actual: Only the `prop` property is allowed
Foo:
type: object
properties:
foo:
type: string
additionalProperties: false
Bar:
allOf:
- $ref: '#/components/schemas/Foo'
- properties:
prop:
type: string
# Expected: The Bar schema allows properties from Foo + the `prop` property
# Actual: The Bar schema allows only properties from Foo
This is solved in OpenAPI 3.1 / JSON Schema 2019-09+ by the new unevaluatedProperties: false keyword. So the following will work the way you expect:
# openapi: 3.1.0
$ref: '#/components/schemas/Foo'
properties:
prop:
type: string
unevaluatedProperties: false
I think the second one: for a long time, schema keywords adjacent to $ref were ignored in json schemas. Later they changed it in the spec (AFAIK), but I'm not sure if all the tooling & implementations caught up with that.
Yet my personal preference is putting both the parent schema and child schema props under an allOf, like
schemas:
FileContent:
allOf:
- $ref: '#/components/schemas/FileInfo'
- type: object
properties:
storageMethod:
$ref: '#/components/schemas/StorageMethod'
contentRange:
type: string
nullable: true
totalLength:
type: integer
format: int64

How to define an OpenAPI ordered array of different objects?

I am trying to define my API using OpenAPI version 3.0. I am trying to generate a YAML file which has four maps, and each map contains a different information. How can I create a YAML file to achieve that goal? I know that my components are not right because of which I am not getting the right result.
Request body should be like this:
[
UserInformation{FirstName, LastName},
AddressInformation{Phone, Address},
ContactInformation{Email, Phone}
]
openapi: 3.0.0
info:
version: 1.0.0
title: 'INPUT-FORM-API'
paths:
/api/v1/test/healthcheck:
get:
summary: Health check for the test api services. Used Internally
operationId: Externalhealthcheck
description: healthcheck for the test services status.
responses:
'200':
description: This status is always returned when service is Ok.
content:
application/json:
schema:
$ref: '#/components/schemas/HealthcheckObject'
/api/v1/test/newformentry:
post:
summary: End Point to insert data into the new table.
operationId: NewFormEntry
description: EndPoint to insert data for new form.
requestBody:
content:
application/json:
schema:
items:
$ref: '#/components/schemas/NewFormEntry'
responses:
'200':
description: This status is always returned when service is Ok.
content:
application/json:
schema:
$ref: '#/components/schemas/HealthcheckObject'
components:
schemas:
NewFormEntry:
$ref: '#/components/schemas/UserInformation'
$ref: '#/components/schemas/AddressInformation'
$ref: '#/components/schemas/ContactInformation'
$ref: '#/components/schemas/MessageFromBene'
UserInformation:
required:
- FirstName
- LastName
properties:
FirstName:
type: string
LastName:
type: string
AddressInformation:
required:
- StreetAddress
- City
- State
- ZipCode
properties:
StreetAddress:
type: string
StreetAddress2:
type: string
City:
type: string
State:
type: string
ZipCode:
type: integer
format: int64
ContactInformation:
required:
- PhoneNumber
- Email
properties:
PhoneNumber:
type: integer
format: int64
maximum: 9
Email:
type: string
HomePhone:
type: integer
format: int64
maximum: 9
Cell:
type: integer
format: int64
maximum: 9
WorkPhone:
type: integer
format: int64
maximum: 9
MessageFromBene:
required:
- Message
properties:
PhoneNumber:
type: integer
format: int64
maximum: 9
Message:
type: string
HealthcheckObject:
required:
- Status
- ErrorMessage
properties:
Status:
type: string
ErrorMessage:
type: string
So the NewFormEntry schema must be an array containing 3 objects, where the 1st object must be UserInformation, the second object must be AddressInformation, and the 3rd object mube be ContactInformation. This is like a tuple, i.e. an ordered sequence of elements where each element has a specfic type. Tuple definitions are slightly different in different OpenAPI versions.
OpenAPI 3.1
If or when you migrate to OAS 3.1, such an array can be defined using prefixItems. This keyword specifies the schema for each element position (in other words, it specifies the order of elements in the array):
components:
schemas:
NewFormEntry:
type: array
prefixItems:
- $ref: '#/components/schemas/UserInformation' # type of the 1st element
- $ref: '#/components/schemas/AddressInformation' # type of the 2nd element
- $ref: '#/components/schemas/ContactInformation' # type of the 3rd element
minItems: 3
maxItems: 3
additionalItems: false # can be omitted if `maxItems: 3` is specified
OpenAPI 3.0
In OAS 3.0, you can define the array length (i.e. 3 items) and the possible types of array items (i.e. each item can be either A, B, or C), but there's no way to define a specific order of objects in the array. So the most you can do is this:
components:
schemas:
NewFormEntry:
type: array
items:
oneOf:
- $ref: '#/components/schemas/UserInformation'
- $ref: '#/components/schemas/AddressInformation'
- $ref: '#/components/schemas/ContactInformation'
minItems: 3
maxItems: 3
Note that this definition allows arbitrary order of objects in the array and also multiple instances of the same object (e.g. [UserInformation, UserInformation, UserInformation]). You might want to implement additional backend validations to verify the desired order of objects in this array.

Can OpenAPI integrate HATEOAS in a useful way?

Is it possible to describe a HATEOAS REST API with OpenAPI?
When I describe the API in HAL Format I would need to define three schemas for it (one for Request Payloads, one for Collection Resource and one for Item Resource). For Example:
components:
schemas:
Link:
type: object
properties:
href:
type: string
hreflang:
type: string
title:
type: string
type:
type: string
deprecation:
type: string
profile:
type: string
name:
type: string
templated:
type: boolean
Links:
type: object
discriminator:
propertyName: _links
properties:
_links:
type: object
additionalProperties:
type: string
$ref: "#/components/schemas/Link"
CollectionModel:
type: object
discriminator:
propertyName: _embedded
properties:
_embedded:
type: object
_links:
type: object
properties:
self:
type: string
profile:
type: string
search:
type: string
CollectionModel_Foo:
type: object
allOf:
- $ref: "#/components/schemas/CollectionModel"
properties:
_embedded:
type: object
properties:
projects:
type: array
items:
$ref: "#/components/schemas/EntityModel_Foo"
EntityModel_Foo:
type: object
allOf:
- $ref: "#/components/schemas/Foo"
- $ref: "#/components/schemas/Links"
Foo:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
bar:
type: string
I don't find that very useful because that complicates the specification and since when generating a client based on that schema using OpenAPI Generator the client does not pay attention to HATEOAS and simply requests the resources. So in this context it is useless.
I thought about implementing JSON:API but sadly the full JSON Schema is only supported in the current OpenAPI 3.1 draft.
All in all I can't find a proper way to integrate OpenAPI in a HATEOAS API.

OpenAPI some unkown values

I'm reading this: OpenAPI 3.0 Tutorial
If I'm looking on one of the examples, there are some things I can't understand
openapi: 3.0.0
info:
version: 1.0.0
title: Simple API
description: A simple API to illustrate OpenAPI concepts
servers:
- url: https://example.io/v1
components:
securitySchemes:
BasicAuth:
type: http
scheme: basic
security:
- BasicAuth: []
paths:
/artists:
get:
description: Returns a list of artists
parameters:
- name: limit
in: query
description: Limits the number of items on a page
schema:
type: integer
- name: offset
in: query
description: Specifies the page number of the artists to be displayed
schema:
type: integer
responses:
'200':
description: Successfully returned a list of artists
content:
application/json:
schema:
type: array
items:
type: object
required:
- username
properties:
artist_name:
type: string
artist_genre:
type: string
albums_recorded:
type: integer
username:
type: string
'400':
description: Invalid request
content:
application/json:
schema:
type: object
properties:
message:
type: string
# ----- Added lines ----------------------------------------
post:
description: Lets a user post a new artist
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- username
properties:
artist_name:
type: string
artist_genre:
type: string
albums_recorded:
type: integer
username:
type: string
responses:
'200':
description: Successfully created a new artist
'400':
description: Invalid request
content:
application/json:
schema:
type: object
properties:
message:
type: string
# ---- /Added lines ----------------------------------------
Why the response of /get contains: required: username ? what is the meaning of this ?
if I don't want basic authentication, can I remove this line ?
Why do we need to write required: true for the requestBody under the post ? It's not basic that post contains body ?
The answer of your questions are:
Why the response of /get contains: required: username? what is the meaning of this? if I don't want basic authentication, can I remove this line?
Ans: Username is required means it's mandatory, i.e. response must contain this field with some value in it. It's not associated with basic authentication. So, yes you can remove that line if it is not used by the application.
Why do we need to write required: true for the requestBody under the post? It's not basic that post contains body?
Ans: Required: true is not mandatory to write here. It's an optional field and post must have a request body. Yeah, you are right. It's a basic thing that posts must have to contain the request body.
If you can have any confusion further then let me know. Thanks

Swagger: how to represent a property whose type is oneOf a list of types?

I have an object that has a property that is an object whose type would be one of list of types. All my attempts have been rejected by Swagger Editor with the following error:
Data does not match any schemas from 'anyOf'
Jump to line 43
Details
Object
code: "ANY_OF_MISSING"
message: "Data does not match any schemas from 'anyOf'"
path: Array [7]
inner: Array [2]
level: 900
type: "Swagger Error"
description: "Data does not match any schemas from 'anyOf'"
lineNumber: 43
The full swagger specification file is as follows (the field in question is DataSetsInquiryRsp.dataSets.dataSet):
swagger: '2.0'
info:
title: My API
description: My Awesome API
version: 1.0.0
paths:
/dataSetsInquiry:
get:
description: Retrieve one or more data-sets.
parameters:
- name: ids
in: query
description: List of identifiers of requested data-sets.
required: true
type: array
items:
type: string
responses:
'200':
description: Requested data-sets.
schema:
$ref: '#/definitions/DataSetsInquiryRsp'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
definitions:
DataSetsInquiryRsp:
type: object
additionalProperties: false
properties:
sessionIdentifier:
description: Identifier of the secure session with the server.
type: number
dataSets:
type: object
additionalProperties: false
properties:
id:
type: string
dataSet:
type: array
items:
oneOf:
- $ref: '#/definitions/Customer'
- $ref: '#/definitions/Merchant'
Customer:
type: object
additionalProperties: false
properties:
firstName:
description: First name of the customer
type: string
lastName:
description: Last name of the customer
type: string
Merchant:
type: object
additionalProperties: false
properties:
code:
description: Code the Merchant.
type: string
name:
description: Name of the Merchant.
type: string
Well, the issue is simply the fact that Swagger doesn't support oneOff. In fact, Swagger supports a subset of Json-Schema and add a few things (datatype file for instance).
What is bad here is the error returned by Swagger. It doesn't help match. And this is the case of all Json-Schema validators I have worked with so far: is-my-json-valid, jsen.

Resources