I am working on an endpoint implementation that wraps multiple endpoints.
There is an endpoint /entity1 implemented in a dependency with its own openapi spec generated in maven plugin to a certain package. And there is an endpoint /entity2 which comes from another dependency.
I am trying to generate a spec for /batch gets an array of entity1 and an array of entity2, like this schema:
paths:
/batch:
post:
description: Batch ingest data
operationId: batchCreate
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Batch'
description: ...
components:
schemas:
Batch:
type: object
properties:
entity1list:
type: array
items:
type: object
entity2list:
type: array
items:
type: object
I currently have the model generated with java plain Object.
Questions:
Is it possible to point the openapi to a different spec loaded in a different package? That would be ideal. Keep in mind I can't import the spec and regenerate the code since it won't do it on different packages.
If not, can I convert the plain Object to Entity1/Entity2?
Solved using the post #Cristian referred to. While generating, it is possible to map certain references. Documentation here
<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>${openapi-generator-maven-plugin.version}</version>
<configuration>
... excluded for simplicity
<importMappings>
<importMapping>SignatureNotification=path.to.your.SignatureNotification</importMapping>
</importMappings>
</configuration>
</plugin>
Related
With org.openapitools:openapi-generator-maven-plugin, I have noticed that using allOf composed of multiple objects in a response does not generate a class combining these multiple objects. Instead it uses the first class defined in the allOf section.
Here is a minimal example (openapi.yaml) :
openapi: 3.0.0
info:
title: Test
version: v1
paths:
/test:
get:
operationId: get
responses:
'200':
description: Get
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/A'
- $ref: '#/components/schemas/B'
components:
schemas:
A:
type: object
properties:
attA:
type: string
B:
type: object
properties:
attB:
type: integer
When generating the classes in Java via :
mvn org.openapitools:openapi-generator-maven-plugin:5.2.0:generate \
-Dopenapi.generator.maven.plugin.inputSpec=openapi.yaml \
-Dopenapi.generator.maven.plugin.generatorName=java
It shows a warning:
[WARNING] allOf with multiple schemas defined. Using only the first one: A
As expected, it generates classes A and B. But, when calling get(), the value returned by the call is of type A:
DefaultApi api = new DefaultApi();
A a = api.get();
Instead, I would have expected a composite object containing A and B properties (attA and attB), like this (result from https://editor.swagger.io/):
I have created an issue on GitHub, but hopefully someone here may have had the same issue and managed to fix it.
Also, I can't modify the openapi.yaml file because it's an OpenAPI spec provided by an API I have to call, so modifying it would make no sense and will make it so difficult to manage if their OpenAPI spec change over time.
Since springdoc-openapi-ui version 1.4.0, I am not able to manage java pojo inheritance anymore.
I know that the concept of AllOf, OneOf has been added in 1.4.0 but I can't figure out how to make it work.
I have a simple pojo that contains a list of X (x is abstract). There's 2 possible implementations. Proper implementation is determine with an attribute of class X.
** Code: (class names has been renamed) **
CheeseDTO YAML in both version :
CheeseDTO:
type: object
properties:
cheeseType:
type: string
discriminator:
propertyName: cheeseType
With springdoc-openapi-ui 1.3.9, my yaml is generated like this:
MyDTO:
type: object
properties:
cheeses:
type: array
items:
$ref: '#/components/schemas/CheeseDTO'
Generated DTO via open openapi-generator-maven-plugin 4.3.0
private List<CheeseDTO> cheeses = null;
With springdoc-openapi-ui 1.5.4, my yaml is generated like this:
MyDTO:
type: object
properties:
cheeses:
type: array
items:
oneOf:
- $ref: '#/components/schemas/SoftCheeseDTO'
- $ref: '#/components/schemas/HardCheeseDTO'
Generated DTO via open openapi-generator-maven-plugin 4.3.0 (This is my issue MyDTOCheesesOneOf instead of CheeseDTO)
private List<MyDTOCheesesOneOf> cheeses = null;
Swagger 3 annotations :
#Schema(
name = "CheeseDTO",
discriminatorProperty = "cheeseType",
discriminatorMapping = {#DiscriminatorMapping(value = "Brie", schema = SoftCheeseDTO.class),
#DiscriminatorMapping(value = "Banon", schema = SoftCheeseDTO.class),
#DiscriminatorMapping(value = "Cheddar", schema = HardCheeseDTO.class)})
abstract CheeseDTO
private String cheeseType;
#Schema(allOf = {CheeseDTO.class})
SoftCheeseDTO extends CheeseDTO
#Schema(allOf = {CheeseDTO.class})
HardCheeseDTO extends CheeseDTO
OpenAPi Generator maven plugin
<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>4.3.0</version>
<executions>
<execution>
<id>generateWebQuoteApiClient</id>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<inputSpec>/definitions/webQuoteApi.yaml</inputSpec>
<generatorName>java</generatorName>
<generateApiDocumentation>false</generateApiDocumentation>
<configOptions>
<library>jersey2</library>
<dateLibrary>java8</dateLibrary>
<java8>true</java8>
<modelPackage>${client.package}.model</modelPackage>
<apiPackage>${client.package}.api</apiPackage>
<invokerPackage>${client.package}.api</invokerPackage>
<performBeanValidation>false</performBeanValidation>
<serializationLibrary>jackson</serializationLibrary>
</configOptions>
</configuration>
</execution>
</executions>
</plugin>
Is there a way to generate a List<CheeseDTO> with springdoc-openapi-ui > 1.4.0 ?
Do i have to change my swagger annotations or change my java generator ?
** I tried update the generator plugin to the latest version but had the same results
Thanks for any help
David
We see same issue with newer sprindoc openapi ui. You need to stick with springdoc-openapi-ui 1.3.9.
Similar issue is on generator:
Until openapi-generator-maven-plugin 4.3.1 you can do it following way:
CheeseDTO:
type: object
properties:
cheeseType:
type: string
discriminator:
propertyName: cheeseType
mapping:
SOFT_CHEESE: '#/components/schemas/SoftCheeseDTO'
HARD_CHEESE: '#/components/schemas/HardCheeseDTO'
And in your API return CheeseDTO:
MyDTO:
type: object
properties:
cheeses:
type: array
items:
$ref: '#/components/schemas/CheeseDTO'
This should correctly generate List<CheeseDTO>.
With newer openapi-generator-maven-plugin 5.x this is not working anymore as propertyName is not supported anymore and oneOf produces wrong inheritance with List<MyDTOCheesesOneOf>.
I use OpenAPI spec to generate Java POJOs. What do I need to specify in Open API yaml to generate the equivalent of below POJO ?
...
#JsonIgnore
public String ignoredProperty;
...
I have the yaml spec as below
openapi: 3.0.0
info:
title: Cool API
description: A Cool API spec
version: 0.0.1
servers:
- url: http://api.cool.com/v1
description: Cool server for testing
paths:
/
...
components:
schemas:
MyPojo:
type: object
properties:
id:
type: integer
name:
type: string
# I want the below attribute to be ignored as a part of JSON
ignoreProperty:
type: string
the openapi generator supports vendor extensions. Specifically, for the Java generator, it supports the following extensions as of the time of writing. However, an up-to-date list can be found here.
Extension name
Description
Applicable for
Default value
x-discriminator-value
Used with model inheritance to specify value for discriminator that identifies current model
MODEL
x-implements
Ability to specify interfaces that model must implements
MODEL
empty array
x-setter-extra-annotation
Custom annotation that can be specified over java setter for specific field
FIELD
When field is array & uniqueItems, then this extension is used to add #JsonDeserialize(as = LinkedHashSet.class) over setter, otherwise no value
x-tags
Specify multiple swagger tags for operation
OPERATION
null
x-accepts
Specify custom value for 'Accept' header for operation
OPERATION
null
x-content-type
Specify custom value for 'Content-Type' header for operation
OPERATION
null
x-class-extra-annotation
List of custom annotations to be added to model
MODEL
null
x-field-extra-annotation
List of custom annotations to be added to property
FIELD
null
x-webclient-blocking
Specifies if method for specific operation should be blocking or non-blocking(ex: return Mono<T>/Flux<T> or return T/List<T>/Set<T> & execute .block() inside generated method)
OPERATION
false
You can use the x-field-extra-annotation vendor extension listed above to add annotations to any field. So, for your example, you can add the following:
openapi: 3.0.0
info:
title: Cool API
description: A Cool API spec
version: 0.0.1
servers:
- url: http://api.cool.com/v1
description: Cool server for testing
paths:
/
...
components:
schemas:
MyPojo:
type: object
properties:
id:
type: integer
name:
type: string
# I want the below attribute to be ignored as a part of JSON
ignoreProperty:
type: string
x-field-extra-annotation: "#com.fasterxml.jackson.annotation.JsonIgnore"
I'm using SpringBoot + Swagger (OpenApi3) + Java for my application. I use the Swagger documentation to import the API into API Gateway.
I have a couple of Java models that both have the following field: List<MyOwnObject> objectList.
When transformed by swagger, I get my models transformed with the same definition for the field:
model1:
type: object
properties:
... // other properties here
objectList:
type: array
items:
$ref: #/components/schemas/MyOwnObject
model2:
type: object
properties:
... // other properties here
objectList:
type: array
items:
$ref: #/components/schemas/MyOwnObject
Now, because of a "feature" in API Gateway, I need to extract these arrays definitions into a single one, referenced in the two models, but I'm not able to find a way to remodel my POJOs to accomplish it.
I require an output similar to this:
model1:
type: object
properties:
... // other properties here
objectList:
$ref: #/components/schemas/commonArray
model2:
type: object
properties:
... // other properties here
objectList:
$ref: #/components/schemas/commonArray
commonArray:
type: array
items:
$ref: #/components/schemas/MyOwnObject
What have I tried
I created a new POJO, containing the list variable. This works, but given that we are adding an extra variable, this affects a current-in-production API schema, which we prefer not to modify.
I created a new POJO extending from ArrayList<MyOwnObject>. During generation, Swagger replaces the new object for the same array schema, leaving the output equal to the original.
I've played with the #Schema and #ArraySchema Swagger annotations without luck.
Do you guys have any idea on how to solve this issue? Is it even possible to accomplish?
Thanks!
In my Spring API designed with Swagger 2.0, I'm trying to create Inheritance using swagger. I want to create a base object, which will have common properties for both Request and Response objects. I tried to do it like the example below:
CategoryResponse:
allOf:
- $ref: '#/definitions/Category'
- type: object
properties:
id:
type: integer
example: '1'
CategoryRequest:
type: object
allOf:
- $ref: '#/definitions/Category'
Category:
discriminator: nameCategory
type: object
properties:
nameCategory:
type: string
example: Games
The problem is that I get a Bad Request error when trying to POST or PUT a new CategoryRequest object. It doesn't even gets to the API Controller, so I guess the problem might in the model definition above. I tried many variations, but none of them worked. However, when I try to GET the list of categories, or one category by id, i'm able to do so (My CategoryResponse is working and extending Category fine).
Does anybody knows the correct way of creating this structure using inheritance of a common base model, both for Request and Response objects?
Thanks in advance!
id looks like an auto-generated and read-only property. In that case you don't need inheritance - you can use a single Category schema and mark id as readOnly: true.
Category:
type: object
properties:
nameCategory:
type: string
example: Games
id:
type: integer
readOnly: true # <-----
example: 1
From the OpenAPI Specification:
readOnly
Declares the property as "read only". This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request.