After defining API specs with RAML, we can use Spring MVC-RAML Maven plugin to generate API contract. With API specs using OpenAPI Specification, you can use OpenAPI Generator Maven plugin to do this. How is it in detail? We will find out together in this tutorial!
First, I will create a new Spring Boot project with Web dependency:
for example.
Result:
As an example, I will use the API specs defined in the tutorial Basic definition of RESTful Web Service API specs using OpenAPI Specification. You can get the content of this API specs here, copy all the files and folders into the src/main/resources/api directory of our project:
Now we will declare the basic OpenAPI Generator Maven plugin as follows:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
<plugin> <groupId>org.openapitools</groupId> <artifactId>openapi-generator-maven-plugin</artifactId> <version>6.0.0</version> <executions> <execution> <goals> <goal>generate</goal> </goals> <configuration> <inputSpec>${project.basedir}/src/main/resources/api/student.yaml</inputSpec> <generatorName>spring</generatorName> <apiPackage>com.huongdanjava.openapispring.web</apiPackage> <modelPackage>com.huongdanjava.openapispring.dto</modelPackage> <output>.</output> <configOptions> <delegatePattern>true</delegatePattern> </configOptions> </configuration> </execution> </executions> </plugin> |
In the configuration section, the <inputSpec> tag will point to the location of the API specs file.
OpenAPI Generator Maven plugin allows us to generate API contracts for many types of projects with different programming languages. You need to declare the Generator name to specify the type of project you want to generate. Generator list here. Here, I have declared to generate a Spring project.
Each Generator defines a lot of different config options, allowing us to generate the project as we want. You declare these config options in the <configOptions> tag. In the above example, I am using a spring generator and I am using a config option of this generator <delegatePattern> with the value to true to use the Delegate Design Pattern in the implementation for API specs, separating the interface class and the implementation part. There are many other config options, you can take a look here.
The <apiPackage> tag is used to declare the package name that the generated Controller classes will use, and <modelPackage> is related to the package that the generated DTO classes will use.
The <output> tag will be the folder containing the generated files. Here I configure this tag with the value “.” to select the current directory. You can use the value “.” or ${project.basedir} is fine.
One point you should note is that when the OpenAPI Generator Maven plugin generates the Spring project for us, it will override the pom.xml file, so please back up the contents of the pom.xml file first. I will tell you how to configure the OpenAPI Generator Maven plugin to skip generate and override the pom.xml file later!
Now, if you run the project with “mvn clean compile”, refresh the project, you will see the following results:
As you can see, the OpenAPI Generator Maven plugin has generated us a Spring project.
Check the pom.xml file, as I said above, you will see that it overrides the pom.xml file as well. To skip generate and override this pom.xml file, please open the .openapi-generator-ignore file in the root directory of the project, and add the line “pom.xml”. Copy the contents of the pom.xml file that you have backed up, the next time you compile, this pom.xml file will not be overridden by the OpenAPI Generator Maven plugin anymore!
Run “mvn clean compile” again, check the console log, you will see the following files are generated:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
INFO] writing file /Users/khanh/Documents/code/huongdanjava.com/openapi-generator-spring/src/main/java/com/huongdanjava/openapispring/dto/Response.java [INFO] writing file /Users/khanh/Documents/code/huongdanjava.com/openapi-generator-spring/src/main/java/com/huongdanjava/openapispring/dto/Student.java [INFO] writing file /Users/khanh/Documents/code/huongdanjava.com/openapi-generator-spring/src/main/java/com/huongdanjava/openapispring/web/StudentsApiController.java [INFO] writing file /Users/khanh/Documents/code/huongdanjava.com/openapi-generator-spring/src/main/java/com/huongdanjava/openapispring/web/StudentsApi.java [INFO] writing file /Users/khanh/Documents/code/huongdanjava.com/openapi-generator-spring/src/main/java/com/huongdanjava/openapispring/web/StudentsApiDelegate.java [INFO] Ignored /Users/khanh/Documents/code/huongdanjava.com/openapi-generator-spring/pom.xml (Ignored by rule in ignore file.) [INFO] writing file /Users/khanh/Documents/code/huongdanjava.com/openapi-generator-spring/README.md [INFO] writing file /Users/khanh/Documents/code/huongdanjava.com/openapi-generator-spring/src/main/java/org/openapitools/OpenAPI2SpringBoot.java [INFO] writing file /Users/khanh/Documents/code/huongdanjava.com/openapi-generator-spring/src/main/java/org/openapitools/RFC3339DateFormat.java [INFO] writing file /Users/khanh/Documents/code/huongdanjava.com/openapi-generator-spring/src/main/resources/application.properties [INFO] writing file /Users/khanh/Documents/code/huongdanjava.com/openapi-generator-spring/src/main/java/org/openapitools/configuration/HomeController.java [INFO] writing file /Users/khanh/Documents/code/huongdanjava.com/openapi-generator-spring/src/main/resources/openapi.yaml [INFO] writing file /Users/khanh/Documents/code/huongdanjava.com/openapi-generator-spring/src/main/java/com/huongdanjava/openapispring/web/ApiUtil.java [INFO] Skipped /Users/khanh/Documents/code/huongdanjava.com/openapi-generator-spring/.openapi-generator-ignore (Skipped by supportingFiles options supplied by user.) [INFO] writing file /Users/khanh/Documents/code/huongdanjava.com/openapi-generator-spring/.openapi-generator/VERSION [INFO] writing file /Users/khanh/Documents/code/huongdanjava.com/openapi-generator-spring/.openapi-generator/FILES |
The package com.huongdanjava.openapispring.dto will contain the DTOs which are the Schema objects that we defined in the YAML file.
The package com.huongdanjava.openapispring.web will contain Controller classes corresponding to URL requests, organized according to the Delegate Design Pattern. In addition, you will also see an ApiUtil class that defines the utility methods used in the Controller classes.
The org.openapitools package defines another Controller, allowing us to get the contents of the src/main/resources/openapi.yaml file generated by the OpenAPI Generator Maven plugin. The content of this openapi.yaml file is converted from the content of our YAML file, which in this example is student.yaml.
The application.properties file is also overridden to add the following properties:
|
1 2 3 |
server.port=8081 spring.jackson.date-format=org.openapitools.RFC3339DateFormat spring.jackson.serialization.WRITE_DATES_AS_TIMESTAMPS=false |
You should also add this application.properties file to the .openapi-generator-ignore “src/main/resources/application.properties” file to avoid overriding!
Some dependencies need to be added to the pom.xml file for our project to be able to compile, as follows:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.6.9</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.dataformat</groupId> <artifactId>jackson-dataformat-yaml</artifactId> </dependency> <dependency> <groupId>org.openapitools</groupId> <artifactId>jackson-databind-nullable</artifactId> <version>0.2.3</version> </dependency> <dependency> <groupId>javax.validation</groupId> <artifactId>validation-api</artifactId> </dependency> |
You also need to edit the code of the Openapi Generator SpringApplication class so that our application can fully scan the Controllers as follows:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
package com.huongdanjava.openapispring; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.context.annotation.ComponentScan; @SpringBootApplication //// @formatter:off @ComponentScan( basePackages = { "org.openapitools", "com.huongdanjava.openapispring", "org.openapitools.configuration" } ) // @formatter:on public class OpenapiGeneratorSpringApplication { public static void main(String[] args) { SpringApplication.run(OpenapiGeneratorSpringApplication.class, args); } } |
Now, if you run the application and go to http://localhost:8081/, you will see the following output:
This is the Swagger API documentation! Using it, you will know how many request URLs our application has exposed. The information of each request URL looks like, and we can use this Swagger API documentation to call the actual request URL.
Currently, we have not implemented URL requests. You can add a new class that implements the StudentsApiDelegate interface to do this. My example is as follows:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
package com.huongdanjava.openapispring.web.impl; import org.springframework.http.ResponseEntity; import org.springframework.stereotype.Service; import com.huongdanjava.openapispring.dto.Student; import com.huongdanjava.openapispring.web.StudentsApiDelegate; @Service public class StudentApiDelegateImpl implements StudentsApiDelegate { @Override public ResponseEntity<Student> getStudentById(String ID) { Student student = new Student(); student.setId(1L); student.setCode("123"); student.setName("HDJ"); return ResponseEntity.ok(student); } } |
The result if we request to the request URL http://localhost:8081/api/students/1 now is as follows:
If you generate Spring Webflux project, please add a config option “reactive”:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
<plugin> <groupId>org.openapitools</groupId> <artifactId>openapi-generator-maven-plugin</artifactId> <version>6.0.0</version> <executions> <execution> <goals> <goal>generate</goal> </goals> <configuration> ... <configOptions> <delegatePattern>true</delegatePattern> <reactive>true</reactive> </configOptions> </configuration> </execution> </executions> </plugin> |
Of course, then, you must add a Spring Webflux dependency so that the project can be compiled:
|
1 2 3 4 |
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-webflux</artifactId> </dependency> |
