Skip to content

Commit 25b0042

Browse files
jpraetjpraet
authored
Add documentation and integration test for code generator configuration (#29)
1 parent bd141a6 commit 25b0042

File tree

8 files changed

+344
-0
lines changed

8 files changed

+344
-0
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,4 @@ target
44
.classpath
55
.idea
66
*.iml
7+
belgif-rest-problem-it/belgif-rest-problem-codegen-it/src/main/resources/belgif

‎belgif-rest-problem-it/belgif-rest-problem-codegen-it/pom.xml‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
4+
<modelVersion>4.0.0</modelVersion>
5+
6+
<parent>
7+
<groupId>io.github.belgif.rest.problem</groupId>
8+
<artifactId>belgif-rest-problem-it</artifactId>
9+
<version>${revision}</version>
10+
</parent>
11+
12+
<artifactId>belgif-rest-problem-codegen-it</artifactId>
13+
14+
<build>
15+
<plugins>
16+
<plugin>
17+
<artifactId>maven-clean-plugin</artifactId>
18+
<configuration>
19+
<filesets>
20+
<fileset>
21+
<directory>${project.basedir}/src/main/resources/belgif</directory>
22+
<includes>
23+
<include>**</include>
24+
</includes>
25+
</fileset>
26+
</filesets>
27+
</configuration>
28+
</plugin>
29+
<plugin>
30+
<artifactId>maven-dependency-plugin</artifactId>
31+
<executions>
32+
<execution>
33+
<id>unpack-belgif-openapi</id>
34+
<phase>generate-sources</phase>
35+
<goals>
36+
<goal>unpack-dependencies</goal>
37+
</goals>
38+
<configuration>
39+
<includeTypes>zip</includeTypes>
40+
<outputDirectory>${project.basedir}/src/main/resources</outputDirectory>
41+
</configuration>
42+
</execution>
43+
</executions>
44+
</plugin>
45+
<plugin>
46+
<groupId>org.openapitools</groupId>
47+
<artifactId>openapi-generator-maven-plugin</artifactId>
48+
<executions>
49+
<execution>
50+
<id>openapi-generator</id>
51+
<goals>
52+
<goal>generate</goal>
53+
</goals>
54+
<configuration>
55+
<generatorName>jaxrs-spec</generatorName>
56+
<generateSupportingFiles>false</generateSupportingFiles>
57+
<inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
58+
<output>${project.build.directory}/generated-sources/openapi-generator</output>
59+
<modelPackage>io.github.belgif.rest.problem.codegen.openapi.model</modelPackage>
60+
<apiPackage>io.github.belgif.rest.problem.codegen.openapi.api</apiPackage>
61+
<configOptions>
62+
<interfaceOnly>true</interfaceOnly>
63+
</configOptions>
64+
<!-- tag::openapi-generator-maven-plugin[] -->
65+
<schemaMappings>
66+
Problem=io.github.belgif.rest.problem.api.Problem,
67+
InputValidationProblem=io.github.belgif.rest.problem.api.InputValidationProblem,
68+
InputValidationIssue=io.github.belgif.rest.problem.api.InputValidationIssue,
69+
InvalidParamProblem=io.github.belgif.rest.problem.api.InvalidParamProblem,
70+
InvalidParam=io.github.belgif.rest.problem.api.InvalidParam
71+
</schemaMappings>
72+
<!-- end::openapi-generator-maven-plugin[] -->
73+
</configuration>
74+
</execution>
75+
</executions>
76+
</plugin>
77+
<plugin>
78+
<groupId>io.swagger.codegen.v3</groupId>
79+
<artifactId>swagger-codegen-maven-plugin</artifactId>
80+
<executions>
81+
<execution>
82+
<id>swagger-codegen</id>
83+
<goals>
84+
<goal>generate</goal>
85+
</goals>
86+
<configuration>
87+
<inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
88+
<language>jaxrs-spec</language>
89+
<output>${project.build.directory}/generated-sources/swagger-codegen</output>
90+
<modelPackage>io.github.belgif.rest.problem.codegen.swagger.model</modelPackage>
91+
<apiPackage>io.github.belgif.rest.problem.codegen.swagger.api</apiPackage>
92+
<generateSupportingFiles>false</generateSupportingFiles>
93+
<configOptions>
94+
<interfaceOnly>true</interfaceOnly>
95+
</configOptions>
96+
<!-- tag::swagger-codegen-maven-plugin[] -->
97+
<importMappings>
98+
Problem=io.github.belgif.rest.problem.api.Problem,
99+
InputValidationProblem=io.github.belgif.rest.problem.api.InputValidationProblem,
100+
InputValidationIssue=io.github.belgif.rest.problem.api.InputValidationIssue,
101+
InvalidParamProblem=io.github.belgif.rest.problem.api.InvalidParamProblem,
102+
InvalidParam=io.github.belgif.rest.problem.api.InvalidParam
103+
</importMappings>
104+
<!-- end::swagger-codegen-maven-plugin[] -->
105+
</configuration>
106+
</execution>
107+
</executions>
108+
</plugin>
109+
<plugin>
110+
<groupId>org.codehaus.mojo</groupId>
111+
<artifactId>build-helper-maven-plugin</artifactId>
112+
<executions>
113+
<execution>
114+
<phase>generate-sources</phase>
115+
<goals>
116+
<goal>add-source</goal>
117+
</goals>
118+
<configuration>
119+
<sources>
120+
<source>${project.build.directory}/generated-sources/openapi-generator/src/gen/java</source>
121+
<source>${project.build.directory}/generated-sources/swagger-codegen/src/gen/java</source>
122+
</sources>
123+
</configuration>
124+
</execution>
125+
</executions>
126+
</plugin>
127+
</plugins>
128+
</build>
129+
130+
<dependencies>
131+
<dependency>
132+
<groupId>io.github.belgif.rest.problem</groupId>
133+
<artifactId>belgif-rest-problem</artifactId>
134+
<version>${project.version}</version>
135+
</dependency>
136+
<dependency>
137+
<groupId>io.github.belgif.openapi</groupId>
138+
<artifactId>belgif-openapi-problem</artifactId>
139+
<version>1.3.1</version>
140+
<type>zip</type>
141+
<classifier>openapi</classifier>
142+
</dependency>
143+
<dependency>
144+
<groupId>io.swagger</groupId>
145+
<artifactId>swagger-annotations</artifactId>
146+
<version>1.6.14</version>
147+
</dependency>
148+
<dependency>
149+
<groupId>io.swagger.core.v3</groupId>
150+
<artifactId>swagger-annotations</artifactId>
151+
<version>2.2.21</version>
152+
</dependency>
153+
<dependency>
154+
<groupId>jakarta.platform</groupId>
155+
<artifactId>jakarta.jakartaee-api</artifactId>
156+
<version>8.0.0</version>
157+
<scope>provided</scope>
158+
</dependency>
159+
<dependency>
160+
<groupId>com.fasterxml.jackson.core</groupId>
161+
<artifactId>jackson-databind</artifactId>
162+
<scope>provided</scope>
163+
</dependency>
164+
<dependency>
165+
<groupId>org.junit.jupiter</groupId>
166+
<artifactId>junit-jupiter</artifactId>
167+
<scope>provided</scope>
168+
</dependency>
169+
<dependency>
170+
<groupId>org.assertj</groupId>
171+
<artifactId>assertj-core</artifactId>
172+
<scope>provided</scope>
173+
</dependency>
174+
</dependencies>
175+
176+
</project>

‎belgif-rest-problem-it/belgif-rest-problem-codegen-it/src/main/resources/openapi.yaml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
openapi: 3.0.3
2+
info:
3+
title: problemCodegenTest
4+
version: "1.0"
5+
servers:
6+
- url: /problemCodegenTest/v1
7+
paths:
8+
/problem:
9+
get:
10+
operationId: getProblem
11+
responses:
12+
"200":
13+
description: Success
14+
content:
15+
application/json:
16+
schema:
17+
$ref: "#/components/schemas/SuccessResponse"
18+
"400":
19+
description: Bad Request
20+
content:
21+
application/problem+json:
22+
schema:
23+
$ref: "belgif/problem/v1/problem-v1.yaml#/components/schemas/InputValidationProblem"
24+
default:
25+
$ref: "belgif/problem/v1/problem-v1.yaml#/components/responses/ProblemResponse"
26+
/legacy:
27+
get:
28+
operationId: getLegacyProblem
29+
responses:
30+
"200":
31+
description: Success
32+
content:
33+
application/json:
34+
schema:
35+
$ref: "#/components/schemas/SuccessResponse"
36+
"400":
37+
description: Bad Request
38+
content:
39+
application/problem+json:
40+
schema:
41+
$ref: "belgif/problem/v1/problem-v1.yaml#/components/schemas/InvalidParamProblem"
42+
default:
43+
$ref: "belgif/problem/v1/problem-v1.yaml#/components/responses/ProblemResponse"
44+
components:
45+
schemas:
46+
SuccessResponse:
47+
type: object
48+
properties:
49+
message:
50+
type: string

‎belgif-rest-problem-it/belgif-rest-problem-codegen-it/src/test/java/io/github/belgif/rest/problem/codegen/OpenApiGeneratorIT.java‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
package io.github.belgif.rest.problem.codegen;
2+
3+
import static org.assertj.core.api.Assertions.*;
4+
5+
import org.junit.jupiter.api.Test;
6+
import org.junit.jupiter.params.ParameterizedTest;
7+
import org.junit.jupiter.params.provider.ValueSource;
8+
9+
import io.github.belgif.rest.problem.codegen.openapi.api.LegacyApi;
10+
import io.github.belgif.rest.problem.codegen.openapi.api.ProblemApi;
11+
import io.github.belgif.rest.problem.codegen.openapi.model.SuccessResponse;
12+
13+
class OpenApiGeneratorIT {
14+
15+
@ParameterizedTest
16+
@ValueSource(strings = {
17+
"Problem", "InputValidationProblem", "InputValidationIssue",
18+
"InvalidParamProblem", "InvalidParam" })
19+
void noProblemModelClassesAreGenerated(String model) {
20+
assertThatExceptionOfType(ClassNotFoundException.class).isThrownBy(
21+
() -> Class.forName("io.github.belgif.rest.problem.codegen.openapi.model." + model));
22+
}
23+
24+
@Test
25+
void apiAndModelClassesAreGenerated() {
26+
assertThat(ProblemApi.class).hasMethods("getProblem");
27+
assertThat(LegacyApi.class).hasMethods("getLegacyProblem");
28+
assertThat(SuccessResponse.class).hasMethods("getMessage");
29+
}
30+
31+
}

‎belgif-rest-problem-it/belgif-rest-problem-codegen-it/src/test/java/io/github/belgif/rest/problem/codegen/SwaggerCodegenIT.java‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
package io.github.belgif.rest.problem.codegen;
2+
3+
import static org.assertj.core.api.Assertions.*;
4+
5+
import org.junit.jupiter.api.Test;
6+
import org.junit.jupiter.params.ParameterizedTest;
7+
import org.junit.jupiter.params.provider.ValueSource;
8+
9+
import io.github.belgif.rest.problem.codegen.swagger.api.LegacyApi;
10+
import io.github.belgif.rest.problem.codegen.swagger.api.ProblemApi;
11+
import io.github.belgif.rest.problem.codegen.swagger.model.SuccessResponse;
12+
13+
class SwaggerCodegenIT {
14+
15+
@ParameterizedTest
16+
@ValueSource(strings = {
17+
"Problem", "InputValidationProblem", "InputValidationIssue",
18+
"InvalidParamProblem", "InvalidParam" })
19+
void noProblemModelClassesAreGenerated(String model) {
20+
assertThatExceptionOfType(ClassNotFoundException.class).isThrownBy(
21+
() -> Class.forName("io.github.belgif.rest.problem.codegen.swagger.model." + model));
22+
}
23+
24+
@Test
25+
void apiAndModelClassesAreGenerated() {
26+
assertThat(ProblemApi.class).hasMethods("getProblem");
27+
assertThat(LegacyApi.class).hasMethods("getLegacyProblem");
28+
assertThat(SuccessResponse.class).hasMethods("getMessage");
29+
}
30+
31+
}

‎belgif-rest-problem-it/pom.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@
4141
<module>belgif-rest-problem-it-common</module>
4242
<module>belgif-rest-problem-jackson-minimal-it</module>
4343
<module>belgif-rest-problem-jackson-latest-it</module>
44+
<module>belgif-rest-problem-codegen-it</module>
4445
</modules>
4546

4647
</project>

‎pom.xml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,16 @@
6868
<build>
6969
<pluginManagement>
7070
<plugins>
71+
<plugin>
72+
<groupId>org.apache.maven.plugins</groupId>
73+
<artifactId>maven-clean-plugin</artifactId>
74+
<version>3.3.2</version>
75+
</plugin>
76+
<plugin>
77+
<groupId>org.apache.maven.plugins</groupId>
78+
<artifactId>maven-dependency-plugin</artifactId>
79+
<version>3.6.1</version>
80+
</plugin>
7181
<plugin>
7282
<groupId>org.apache.maven.plugins</groupId>
7383
<artifactId>maven-compiler-plugin</artifactId>
@@ -123,11 +133,26 @@
123133
<artifactId>flatten-maven-plugin</artifactId>
124134
<version>1.6.0</version>
125135
</plugin>
136+
<plugin>
137+
<groupId>org.codehaus.mojo</groupId>
138+
<artifactId>build-helper-maven-plugin</artifactId>
139+
<version>3.5.0</version>
140+
</plugin>
126141
<plugin>
127142
<groupId>com.diffplug.spotless</groupId>
128143
<artifactId>spotless-maven-plugin</artifactId>
129144
<version>2.43.0</version>
130145
</plugin>
146+
<plugin>
147+
<groupId>org.openapitools</groupId>
148+
<artifactId>openapi-generator-maven-plugin</artifactId>
149+
<version>7.5.0</version>
150+
</plugin>
151+
<plugin>
152+
<groupId>io.swagger.codegen.v3</groupId>
153+
<artifactId>swagger-codegen-maven-plugin</artifactId>
154+
<version>3.0.54</version>
155+
</plugin>
131156
<plugin>
132157
<groupId>org.sonarsource.scanner.maven</groupId>
133158
<artifactId>sonar-maven-plugin</artifactId>

‎src/main/asciidoc/index.adoc‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,10 @@ The library consists of these modules:
4545
* Remove `be.fgov.kszbcss` from default scanned problem type packages
4646
* Rename `io.github.belgif.rest.problem.spring.scan-additional-problem-packages` configuration property to `io.github.belgif.rest.problem.scan-additional-problem-packages`
4747

48+
*documentation:*
49+
50+
* Add chapter on <<code-generators>>
51+
4852
=== Version 0.1
4953

5054
Initial release under Belgif organization.
@@ -312,3 +316,28 @@ io.github.belgif.rest.problem.scan-additional-problem-packages=com.acme.custom
312316
This handles integration with the https://docs.spring.io/spring-framework/reference/web/webflux-webclient.html[Reactive WebClient].
313317

314318
In general, these components make it possible to use standard java exception handling (throw and try-catch) for dealing with problems in Spring Boot REST APIs.
319+
320+
[[code-generators]]
321+
== Code generators
322+
323+
Code generators should be configured to use the belgif-rest-problem types for problem-related model classes, instead of generating them.
324+
325+
[[openapi-generator-maven-plugin]]
326+
=== openapi-generator-maven-plugin
327+
328+
When using https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin[openapi-generator-maven-plugin], configure `<schemaMappings>` as follows:
329+
330+
[source,xml,indent=0]
331+
----
332+
include::../../../belgif-rest-problem-it/belgif-rest-problem-codegen-it/pom.xml[tag=openapi-generator-maven-plugin]
333+
----
334+
335+
[[swagger-codegen-maven-plugin]]
336+
=== swagger-codegen-maven-plugin
337+
338+
When using https://github.com/swagger-api/swagger-codegen/tree/3.0.0/modules/swagger-codegen-maven-plugin[swagger-codegen-maven-plugin], configure `<importMappings>` as follows:
339+
340+
[source,xml,indent=0]
341+
----
342+
include::../../../belgif-rest-problem-it/belgif-rest-problem-codegen-it/pom.xml[tag=swagger-codegen-maven-plugin]
343+
----

0 commit comments

Comments
 (0)