We Keep Coding

Use OpenAPI to generate Java APIs that don't return ResponseEntity

I want to generate a Java API using OpenAPI 3.0, but I don't want any return type to be a ResponseEntity.
I have a small .yaml file that generates APIs that look like this (I've removed lots of annotations for brevity):
#GetMapping(value = "/student", produces = { "application/json" })
ResponseEntity<List<Student>> getAllStudents();
It's very straightforward, but my employer wants an API like this:
#GetMapping(value = "/student")
List<Student> getAllStudents();
The trouble is that I can't find a configuration option that would make the code generator dispense with the ResponseEntities.
Is there any way to configure the OpenAPI generator to not use ResponseEntities?
—
Details:
I build with Maven, and I configure my code generation in my pom file like this:
<build>
<plugins>
<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<!-- RELEASE_VERSION -->
<version>5.0.0-SNAPSHOT</version>
<!-- /RELEASE_VERSION -->
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<!--See https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin-->
<inputSpec>${project.basedir}/OpenApi.yaml</inputSpec>
<generatorName>spring</generatorName>
<groupId>com.dummy.example</groupId>
<artifactId>dummy</artifactId>
<artifactVersion>2.0</artifactVersion>
<library>spring-boot</library>
<packageName>com.neptunedreams.configuration</packageName>
<apiPackage>com.neptunedreams.api</apiPackage>
<invokerPackage>com.neptunedreams</invokerPackage>
<modelPackage>com.neptunedreams.model</modelPackage>
<configOptions>
<!--See https://github.com/OpenAPITools/openapi-generator/blob/master/docs/generators/spring.md -->
<sourceFolder>src/main/java</sourceFolder>
<bigDecimalAsString>true</bigDecimalAsString>
<dateLibrary>java8</dateLibrary>
<interfaceOnly>true</interfaceOnly>
<library>spring-boot</library>
<skipDefaultInterface>true</skipDefaultInterface>
</configOptions>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
My yaml file is very basic, if you need to see it:
openapi: 3.0.0
info:
description: StackOverflow ResponseEntity Question
version: 1.0.0
title: ResponseEntity Question
paths:
/student:
get:
summary: Get all students
operationId: getAllStudents
responses:
200:
description: Get all students
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Student'
components:
schemas:
Student:
type: object
properties:
name:
type: string
id:
type: integer
format: int64
required:
- name
- id

Like here How to prevent Mono Request body generation when generating the API interfaces for spring-webflux with open api code generator?
You can override/customize the api.mustache from swagger-codegen template.
Here you can find the original template https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/main/resources/JavaSpring/api.mustache
So you can put your own template inside src/main/java/resource.
openApiGenerate {
generatorName = "spring"
library = "spring-boot"
...
configOptions = [
...
templateDirectory: "src/main/resources/openapi-templates"
...
]
}
Here is the documentation about template https://github.com/OpenAPITools/openapi-generator/blob/master/docs/templating.md

Generate a property as schema definition in OpenApi 3.0

When using swagger 2.0, the java.util.Currency class got generated as a seperate definition. But when we generate OpenAPI 3.0, we run into the issue that swagger-core generates it as a property.
Generation of the OpenAPI 3.0 specification from the classes
We have f.e. this class:
import java.util.Currency;
public class Wrapper {
private Currency currency;
}
From this code we generate the openapi specification with the following plugin configuration:
<plugin>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<version>2.0.9</version>
<configuration>
<outputFileName>openapi</outputFileName>
<outputFormat>YAML</outputFormat>
<outputPath>....</outputPath>
<resourcePackages>...</resourcePackages>
</configuration>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>resolve</goal>
</goals>
</execution>
</executions>
</plugin>
When generated this will result in this component definition:
components:
schemas:
Wrapper:
type: "object"
properties:
currency:
type: object
properties:
currencyCode:
type: string
defaultFractionDigits:
type: integer
format: int32
numericCode:
type: integer
format: int32
displayName:
type: string
symbol:
type: string
Generation of the classes from the OpenAPI 3.0 specification
We then then generate the classes in another project with the following plugin:
The code to generate the classes form this openapi specification:
<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>3.2.0</version>
<executions>
<execution>
<id>openapi-generation</id>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<inputSpec>${project.basedir}/src/main/resources/swagger.yaml</inputSpec>
<language>java</language>
<library>jersey2</library>
<generateSupportingFiles>false</generateSupportingFiles>
<configOptions>
<booleanGetterPrefix>is</booleanGetterPrefix>
<dateLibrary>threetenbp</dateLibrary>
<import-mappings>
Currency=java.util.Currency
</import-mappings>
</configOptions>
<generateApis>false</generateApis>
<generateApiDocumentation>false</generateApiDocumentation>
<generateModelTests>false</generateModelTests>
<generateModelDocumentation>false</generateModelDocumentation>
</configuration>
</execution>
</executions>
</plugin>
This will result in a class named WrapperCurrency. The --import-mappings option does not seem to work since it's a property and not a schema. This would work if the Currency would be generated as a seperate Schema definition.
Desired result
Is there any way to either, annotate the property in such a way that the java.util.Currency will be generated as a schema? something along the lines of:
components:
schemas:
Wrapper:
type: "object"
properties:
currency:
$ref: "components/schemas/Currency"
Currency:
type: object
properties:
currencyCode:
type: string
defaultFractionDigits:
type: integer
format: int32
numericCode:
type: integer
format: int32
displayName:
type: string
symbol:
type: string
Or is there a way to bind the --import-mappings option to a property instead of the object?

Well, you may consider a workaround: adding an annotation #Schema(ref = "Currency") to the currency field will make the plugin skip generating properties. Unfortunately, it won't generate the schema definition for the Currency class either:
components:
schemas:
Wrapper:
type: object
properties:
currency:
$ref: '#/components/schemas/Currency'
I am not sure if it is an issue for you, as you are mapping it back to java.util.Currency anyways. But if it is, there is another hack: you can provide a static file with a partial schema (just the Currency definition) and configure the plugin to merge it with the generated schema (openapiFilePath parameter).
Plugin configuration:
<plugin>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<version>2.0.9</version>
<configuration>
...
<openapiFilePath>src/main/resources/currency.yaml</openapiFilePath>
...
</configuration>
...
</plugin>
currency.yaml:
components:
schemas:
Currency:
type: object
properties:
currencyCode:
type: string
defaultFractionDigits:
type: integer
format: int32
numericCode:
type: integer
format: int32
displayName:
type: string
symbol:
type: string
It's a hack, I know, but if there are no other options...

Why openapi-generator-maven-plugin ignores my xml tag names?

I am using the openapi-generator-maven-plugin
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>4.1.3</version>
with the <withXml>true</withXml> option.
In my yaml service definition file to describe my REST actions (XML messages). I have a schema like this :
components:
schemas:
LoginRequest:
type: object
properties:
customerName:
type: string
xml:
name: customerName
attribute: false
wrapped: false
password:
type: string
xml:
name: hello
attribute: false
user:
type: string
xml:
name: user
attribute: false
wrapped: false
title: request
xml:
name: request
attribute: false
and the defined service :
paths:
/session/login:
post:
tags:
- sample-controller
summary: login
operationId: loginUsingPOST
requestBody:
content:
application/xml:
schema:
$ref: "#/components/schemas/LoginRequest"
description: request
required: true
responses:
"200":
description: OK
content:
application/xml:
schema:
$ref: "#/components/schemas/LoginResponse"
And I generate the client code. But when I use it, the XML sent to the http request uses <LoginRequest> has a tag name instead of <request>.
It seems that none of my -xml information are taken in account by the generator.

You will need to put the option inside configOptions, for example
<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<!-- RELEASE_VERSION -->
<version>4.2.0</version>
<!-- /RELEASE_VERSION -->
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<inputSpec>${project.basedir}/src/main/resources/api.yaml</inputSpec>
<generatorName>java</generatorName>
<configOptions>
<sourceFolder>src/gen/java/main</sourceFolder>
</configOptions>
</configuration>
</execution>
</executions>
</plugin>
Ref: https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin#usage

Spock Error:Groovyc: Could not instantiate global transform class

I m new to Spock, tried to write a simple Spock but it failed:
Error:Groovyc: Could not instantiate global transform class org.spockframework.compiler.SpockTransform specified at jar:file:.../.m2/repository/org/spockframework/spock-core/1.0-groovy-2.4/spock-core-1.0-groovy-2.4.jar!/META-INF/services/org.codehaus.groovy.transform.ASTTransformation because of exception java.lang.NullPointerException
here is my Spec:
#Unroll
class UserFilterSpec extends Specification {
private static final String USER_ID_1 = "someUserId1";
private static final String USER_ID_2 = "someUserId2";
private static final String USER_ID_3 = "someUserId3";
def filter = new UserFilter()
def User user1 = setupTestUser(USER_ID_1)
def User user2 = setupTestUser(USER_ID_2)
def User user3 = setupTestUser(USER_ID_3)
def "given a list of users and list of user ids, should return list of user with those users removed"() {
expect:
filter.filterUserDataByIds(userList, userIdList) == filterList
where:
userList | userIdList || filterList
Lists.newArrayList(user1, user2, user3) | Lists.newArrayList(USER_ID_1) || Lists.newArrayList(user2, user3)
}
}
and here is my pom.xml:
<!-- Mandatory plugins for using Spock -->
<plugin>
<!-- The gmavenplus plugin is used to compile Groovy code. To learn more about this plugin,
visit https://github.com/groovy/GMavenPlus/wiki -->
<groupId>org.codehaus.gmavenplus</groupId>
<artifactId>gmavenplus-plugin</artifactId>
<version>1.4</version>
<executions>
<execution>
<goals>
<goal>compile</goal>
<goal>testCompile</goal>
</goals>
</execution>
</executions>
</plugin>
<!-- Optional plugins for using Spock -->
<!-- Only required if names of spec classes don't match default Surefire patterns (`*Test` etc.) -->
<plugin>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.6</version>
<configuration>
<useFile>false</useFile>
<includes>
<include>**/*Spec.java</include>
<include>**/*Test.java</include> <!-- Just in case of having also "normal" JUnit tests -->
</includes>
</configuration>
</plugin>
...
<!-- Mandatory dependencies for using Spock -->
<dependency>
<groupId>org.spockframework</groupId>
<artifactId>spock-core</artifactId>
<version>1.0-groovy-2.4</version>
<scope>test</scope>
</dependency>
<!-- Optional dependencies for using Spock -->
<dependency> <!-- use a specific Groovy version rather than the one specified by spock-core -->
<groupId>org.codehaus.groovy</groupId>
<artifactId>groovy-all</artifactId>
<version>2.4.1</version>
</dependency>
<dependency> <!-- enables mocking of classes (in addition to interfaces) -->
<groupId>cglib</groupId>
<artifactId>cglib-nodep</artifactId>
<version>3.1</version>
<scope>test</scope>
</dependency>
<dependency> <!-- enables mocking of classes without default constructor (together with CGLIB) -->
<groupId>org.objenesis</groupId>
<artifactId>objenesis</artifactId>
<version>2.1</version>
<scope>test</scope>
</dependency>
what is wrong my Spec or pom setting? do i have to install Groovy to make it work?

Here is your test, re-written in more idiomatic Spock/Groovy:
#Unroll
class UserFilterSpec extends Specification {
static final String USER_ID_1 = "someUserId1"
static final String USER_ID_2 = "someUserId2"
static final String USER_ID_3 = "someUserId3"
#Shared user1 = setupTestUser(USER_ID_1)
#Shared user2 = setupTestUser(USER_ID_2)
#Shared user3 = setupTestUser(USER_ID_3)
#Shared filter = new UserFilter()
def "given a list of users and list of user ids, should return list of user with those users removed"() {
expect:
filter.filterUserDataByIds(userList, userIdList) == filterList
where:
userList | userIdList || filterList
[user1, user2, user3] | [USER_ID_1] || [user2, user3]
}
}
A couple of notes:
Groovy (in which Spock tests are written) has native support for declaring collections. Thus [user1, user3] instead of Lists.newArrayList.
#Shared or static is required for class-level variables that are used in tests. This will solve your compilation problem.
I highly recommend reading the Groovy user guide, it's a great read and will help you immensely getting started with Spock. The style guide is here: http://www.groovy-lang.org/style-guide.html, and from there you can explore the Documentation page for other interesting tidbits.
The Spock documentation is also excellent, and can easily be read in one sitting: http://docs.spockframework.org.

Add static or #Shared for non-method variables - 'filter', 'user 1-3'.
You can`t access non static class properties from inside the 'where' section.

In my case I solved the groovy error by upgrading from spring boot 2.3.4 to 2.5.3
https://issueexplorer.com/issue/spockframework/spock-example/44
Also, try upgrading from 1.3-groovy-2.5 to 2.0-groovy-3.0

Generate JAXB classes with equals() from schemas with relative schemaLocation in multiple Maven modules

I have a Maven project with 3 modules: schema, gml and adress. schema contains two XSDs: gmlprofil-1.1.xsd - a simple GML profile and adress.xsd which imports the GML schema using a relative schemaLocation, like so:
<import schemaLocation="../gml/gmlprofil-1.1.xsd" namespace="http://www.opengis.net/gml/3.2"/>
In both the gml module and the adress module, I use maven-jaxb2-plugin with jaxb2-basics in order to generate classes with equals() and hashCode(). The gml module works fine, but when running adress, I get this error:
com.sun.istack.SAXParseException2; IOException thrown when processing "../gml/gmlprofil-1.1.xsd". Exception: java.io.FileNotFoundException: C:\code\gml\gmlprofil-1.1.xsd
Fine. A catalog file to the rescue!
REWRITE_SYSTEM "../gml/gmlprofil-1.1.xsd" "maven:com.test:schema:jar::!/com/test/schemas/gml/gmlprofil-1.1.xsd"
It looks like the absolute path is resolved OK, but then a MalformedURLException occurs.
[DEBUG] Parent resolver has resolved publicId [null], systemId [../gml/gmlprofil-1.1.xsd] to [maven:com.test:schema:jar::!/com/test/schemas/gml/gmlprofil-1.1.xsd].
[DEBUG] Resolving systemId [maven:com.test:schema:jar::!/com/test/schemas/gml/gmlprofil-1.1.xsd] as Maven dependency resource.
[DEBUG] Resolved dependency resource [Dependency {groupId=com.test, artifactId=schema, version=1.0-SNAPSHOT, type=jar, classifier=null, resource=com/test/schemas/gml/gmlprofil-1.1.xsd}] to resource URL [jar:file:/C:/code/jaxb-test/schema/target/schema-1.0-SNAPSHOT.jar!/com/test/schemas/gml/gmlprofil-1.1.xsd].
[DEBUG] Resolved systemId [maven:com.test:schema:jar::!/com/test/schemas/gml/gmlprofil-1.1.xsd] to [jar:file:/C:/code/jaxb-test/schema/target/schema-1.0-SNAPSHOT.jar!/com/test/schemas/gml/gmlprofil-1.1.xsd].
[ERROR] Error while parsing schema(s).Location [ maven:com.test:schema:jar::!/com/test/schemas/adress/adress.xsd{8,97}].
org.xml.sax.SAXParseException; systemId: maven:com.test:schema:jar::!/com/test/schemas/adress/adress.xsd; lineNumber: 8; columnNumber: 97; unknown protocol: maven
...
Caused by: java.net.MalformedURLException: unknown protocol: maven
This is my pom for adress:
<plugin>
<groupId>org.jvnet.jaxb2.maven2</groupId>
<artifactId>maven-jaxb2-plugin</artifactId>
<version>0.13.0</version>
<executions>
<execution>
<phase>generate-sources</phase>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
<configuration>
<bindingDirectory>src/main/resources</bindingDirectory>
<episode>true</episode>
<useDependenciesAsEpisodes>true</useDependenciesAsEpisodes>
<extension>true</extension>
<forceRegenerate>false</forceRegenerate>
<schemaLanguage>XMLSCHEMA</schemaLanguage>
<strict>false</strict>
<verbose>false</verbose>
<catalog>src/main/resources/catalog.cat</catalog>
<args>
<arg>-npa</arg>
<arg>-XsimpleEquals</arg>
<arg>-XsimpleHashCode</arg>
</args>
<plugins>
<plugin>
<groupId>org.jvnet.jaxb2_commons</groupId>
<artifactId>jaxb2-basics</artifactId>
<version>0.9.5</version>
</plugin>
</plugins>
<schemas>
<schema>
<dependencyResource>
<groupId>com.test</groupId>
<artifactId>schema</artifactId>
<resource>com/test/schemas/adress/adress.xsd</resource>
</dependencyResource>
</schema>
</schemas>
</configuration>
</plugin>
I have tried some solutions:
Setting the Maven URL as the schemaLocation:
<import schemaLocation="maven:com.test:schema:jar::!/com/test/schemas/gml/gmlprofil-1.1.xsd" namespace="http://www.opengis.net/gml/3.2"/>
Setting an absolute schemaLocation and updating the catalog file accordingly:
<import schemaLocation="http://test.com/schemas/gml/gmlprofil-1.1.xsd" namespace="http://www.opengis.net/gml/3.2"/>
REWRITE_SYSTEM "http://test.com/schemas" "maven:com.test:schema:jar::!/com/test/schemas"
Lowering the maven-jaxb2-plugin version to 0.9.1. Using this method, I don't even need a catalog file, however I get this error instead:
[ERROR] Failed to execute goal org.jvnet.jaxb2.maven2:maven-jaxb2-plugin:0.9.1:generate (default) on project adress: Execution default of goal org.jvnet.jaxb2.maven2:maven-jaxb2-plugin:0.9.1:generate failed: A required class was missing while executing org.jvnet.jaxb2.maven2:maven-jaxb2-plugin:0.9.1:generate: com/sun/tools/xjc/model/Aspect
This can be resolved by swapping in -Xequals and -XhashCode instead of -XsimpleEquals and -XsimpleHashCode.
All three solutions work, but none is perfect. The first two require manipulating the schema, while the third introduces an unwanted dependency on jaxb2-basics-runtime in the generated classes. The latter is acceptable but I would greatly appreciate it if anyone knows how to run simpleEquals with my setup.

Well, welcome to my world of pain.
You're surely aware of the ogc-schema project, right?
The interesting part is actually that catalog even seems to resolved correctly. Not sure what's happening there but here's the solution I've finally found out to work best:
Compile the absolute URL:
<schemas>
<schema>
<url>http://test.com/schemas/adres/adres.xsd</url>
</schema>
</schemas>
Use a catalog to rewrite
REWRITE_SYSTEM "http://test.com/schemas" "maven:com.test:schema:jar::!/com/test/schemas"
This is basicallyyour third solution but you don't have to change the schema. Just start from an absolute URL, it will be rewritten by the catalog.
Ah, yes:
DISCLAIMER I'm the author of maven-jaxb2-plugin, jaxb2-basics as well as the ogc-schema project mentioned above.
By the way, what's so bad about the jaxb2-basics-runtime dependency?