Sau khi định nghĩa API specs với RAML, chúng ta có thể sử dụng Spring MVC-RAML Maven plugin để generate API contract. Với API specs sử dụng OpenAPI specification thì các bạn có thể sử dụng OpenAPI Generator Maven plugin để làm điều này. Cụ thể như thế nào? Chúng ta sẽ cùng nhau tìm hiểu trong bài viết này các bạn nhé!
Đầu tiên, mình sẽ tạo mới một Maven project:
để làm ví dụ.
Cho ví dụ của bài viết này, mình sẽ sử dụng một API specs mà mình đã định nghĩa ở địa chỉ GitHub này https://github.com/khanhnguyenj/student-management-openapi-specs. Các bạn có thể lấy nội dung của API specs, copy tất cả các tập tin, folder vào thư mục src/main/resources/api của project của chúng ta:
Bây giờ chúng ta sẽ khai báo OpenAPI Generator Maven plugin cơ bản như sau:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
<plugin> <groupId>org.openapitools</groupId> <artifactId>openapi-generator-maven-plugin</artifactId> <version>7.15.0</version> <executions> <execution> <goals> <goal>generate</goal> </goals> <configuration> <inputSpec>${project.basedir}/src/main/resources/api/api.yml</inputSpec> <artifactId>openapi-generator-spring</artifactId> <groupId>com.huongdanjava.openapi</groupId> <generatorName>spring</generatorName> <apiPackage>com.huongdanjava.openapi.web</apiPackage> <modelPackage>com.huongdanjava.openapi.dto</modelPackage> <output>.</output> <configOptions> <delegatePattern>true</delegatePattern> <useSpringBoot3>true</useSpringBoot3> </configOptions> </configuration> </execution> </executions> </plugin> |
Ở phần configuration, tag <inputSpec> dùng để định nghĩa location của tập tin API specs mà chúng ta muốn generate source code đó các bạn!
Tag <artifactId> dùng để định nghĩa artifactId, còn tag <groupId> dùng để định nghĩa groupId cho generated project.
OpenAPI Generator Maven plugin cho phép chúng ta có thể generate API contract cho nhiều loại project với ngôn ngữ lập trình khác nhau. Các bạn cần khai báo Generator name để chỉ định loại project mà mình muốn generate các bạn nhé! Danh sách Generator ở đây. Ở đây, mình đã khai báo để generate Spring project.
Mỗi Generator định nghĩa rất nhiều config option khác nhau, cho phép chúng ta generate project theo ý muốn của mình. Các bạn khai báo các config option này trong tag <configOptions>. Trong ví dụ trên, mình đang sử dụng spring generator và mình đang sử dụng hai configOption của generator này là <delegatePattern> và <useSpringBoot3>. Option <delegatePattern> với giá trị true sẽ sử dụng Delegate Design Pattern trong phần implementation cho API specs, tách biệt giữa interface class và phần implementation. Còn option <useSpringBoot3> là để generate Spring Boot 3 đó các bạn! Còn rất nhiều config option khác, các bạn có thể take a look thêm ở đây nhé.
Tag <apiPackage> dùng để khai báo tên package mà các Controller class được generate sẽ sử dụng, còn <modelPackage> thì liên quan đến package mà các DTO class được generate sẽ sử dụng.
Tag <output> sẽ là folder chứa các tập tin được generate. Ở đây mình cấu hình tag này với giá trị “.” để chọn thư mục hiện hành. Các bạn có thể sử dụng giá trị “.” hoặc ${project.basedir} đều được.
Một điểm các bạn cần lưu ý là khi OpenAPI Generator Maven plugin generate Spring project cho chúng ta, nó sẽ override cả tập tin pom.xml, nên lúc này các bạn hãy backup lại nội dung của tập tin pom.xml trước. Mình sẽ nói các bạn cách cấu hình để OpenAPI Generator Maven plugin skip generate và override tập tin pom.xml sau!
Lúc này, nếu các bạn run project với “mvn clean compile”, refresh project, các bạn sẽ thấy kết quả như sau:
Như các bạn thấy, OpenAPI Generator Maven plugin đã generate cho chúng ta một Spring project.
Kiểm tra tập tin pom.xml, như mình đã nói ở trên, các bạn sẽ thấy nó override luôn cả tập tin pom.xml. Để skip generate và override tập tin pom.xml này, các bạn hãy mở tập tin .openapi-generator-ignore trong thư mục root của project, và thêm dòng “pom.xml” là được. Những lần compile sau, tập tin pom.xml này sẽ không bị OpenAPI Generator Maven plugin override nữa! Bây giờ thì các bạn có thể copy lại nội dung mà các bạn đã định nghĩa cho OpenAPI Generator Maven plugin trong tập tin pom.xml mà các bạn đã backup và paste trở lại tập tin pom.xml hiện tại là được.
Chạy lại “mvn clean compile”, kiểm tra console log, các bạn sẽ thấy những tập tin sau được generate:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
[INFO] writing file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/src/main/java/com/huongdanjava/openapi/dto/AddNewStudentResponse.java [INFO] writing file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/src/main/java/com/huongdanjava/openapi/dto/DeleteStudentResponse.java [INFO] writing file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/src/main/java/com/huongdanjava/openapi/dto/GetAllStudentsResponse.java [INFO] writing file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/src/main/java/com/huongdanjava/openapi/dto/GetStudentByIdResponse.java [INFO] writing file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/src/main/java/com/huongdanjava/openapi/dto/InlineObject.java [INFO] writing file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/src/main/java/com/huongdanjava/openapi/dto/InlineObject1.java [INFO] writing file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/src/main/java/com/huongdanjava/openapi/dto/Student.java [INFO] writing file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/src/main/java/com/huongdanjava/openapi/dto/UpdateStudentResponse.java [INFO] Implementation file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/src/main/java/com/huongdanjava/openapi/web/StudentsApiController.java is not overwritten [INFO] writing file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/src/main/java/com/huongdanjava/openapi/web/StudentsApi.java [INFO] writing file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/src/main/java/com/huongdanjava/openapi/web/StudentsApiDelegate.java [INFO] Skipping generation of Webhooks. [INFO] Ignored /Users/khanhnguyenj/Documents/code/openapi-generator-spring/pom.xml (Ignored by rule in ignore file.) [INFO] writing file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/README.md [INFO] writing file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/src/main/java/org/openapitools/OpenApiGeneratorApplication.java [INFO] writing file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/src/test/java/org/openapitools/OpenApiGeneratorApplicationTests.java [INFO] writing file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/src/main/java/org/openapitools/RFC3339DateFormat.java [INFO] writing file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/src/main/resources/application.properties [INFO] writing file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/src/main/java/org/openapitools/configuration/HomeController.java [INFO] writing file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/src/main/resources/openapi.yaml [INFO] writing file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/src/main/java/org/openapitools/configuration/SpringDocConfiguration.java [INFO] writing file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/src/main/java/com/huongdanjava/openapi/web/ApiUtil.java [INFO] Skipped /Users/khanhnguyenj/Documents/code/openapi-generator-spring/.openapi-generator-ignore (Skipped by supportingFiles options supplied by user.) [INFO] writing file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/.openapi-generator/VERSION [INFO] writing file /Users/khanhnguyenj/Documents/code/openapi-generator-spring/.openapi-generator/FILES |
Package com.huongdanjava.openapi.dto sẽ chứa các DTO là các Schema object mà chúng ta định nghĩa trong tập tin YAML.
Package com.huongdanjava.openapi.web sẽ chứa các Controller class tương ứng với các request URL, được tổ chức theo Delegate Design Pattern. Ngoài ra các bạn còn thấy một class ApiUtil định nghĩa các utility method sử dụng trong các Controller class.
Một tập tin src/main/resources/openapi.yaml cũng được generate bởi OpenAPI Generator Maven plugin. Nội dung của tập tin openapi.yaml này được convert từ nội dung của tập tin YAML của chúng ta đó các bạn!
Tập tin application.properties cũng được generate với một số properties sau:
|
1 2 3 |
server.port=8081 spring.jackson.date-format=org.openapitools.RFC3339DateFormat spring.jackson.serialization.WRITE_DATES_AS_TIMESTAMPS=false |
Các bạn cũng nên add tập tin application.properties này vào tập tin .openapi-generator-ignore “src/main/resources/application.properties” để khỏi bị override nữa!
Package org.openapitools định nghĩa một Controller dùng để chạy Swagger UI. Package này cũng định nghĩa một class với anotation @SpringBootApplication. Chúng ta sẽ sử dụng class này để chạy ứng dụng Spring Boot các bạn nhé!
Bây giờ, nếu các bạn chạy ứng dụng và đi đến http://localhost:8081/, các bạn sẽ thấy kết quả như sau:
Đây chính là Swagger API documentation đó các bạn! Sử dụng nó, các bạn sẽ biết ứng dụng của chúng ta có bao nhiêu request URL được expose. Thông tin của mỗi request URL như thế nào, và chúng ta có thể sử dụng Swagger API documentation này để gọi đến các request URL thực tế luôn.
Hiện tại thì chúng ta chưa implement cho các request URL. Các bạn có thể thêm mới class implement interface StudentsApiDelegate để làm điều này. Ví dụ của mình như sau:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
package com.huongdanjava.openapi.web; import com.huongdanjava.openapi.dto.GetStudentByIdResponse; import com.huongdanjava.openapi.dto.Student; import org.springframework.http.ResponseEntity; import org.springframework.stereotype.Service; @Service public class StudentApiDelegateImpl implements StudentsApiDelegate { @Override public ResponseEntity<GetStudentByIdResponse> getStudentById(String id) { GetStudentByIdResponse getStudentByIdResponse = new GetStudentByIdResponse(); getStudentByIdResponse.success(true); Student student = new Student(); student.setId(1L); student.setCode("123"); student.setName("HDJ"); getStudentByIdResponse.setData(student); return ResponseEntity.ok(getStudentByIdResponse); } } |
Kết quả nếu chúng ta request tới request URL http://localhost:8081/api/students/1 lúc này như sau:
Nếu các bạn generate Spring Webflux project thì hãy thêm một config option là “reactive” nhé:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
<plugin> <groupId>org.openapitools</groupId> <artifactId>openapi-generator-maven-plugin</artifactId> <version>7.15.0</version> <executions> <execution> <goals> <goal>generate</goal> </goals> <configuration> ... <configOptions> <delegatePattern>true</delegatePattern> <useSpringBoot3>true</useSpringBoot3> <reactive>true</reactive> </configOptions> </configuration> </execution> </executions> </plugin> |
Tất nhiên khi đó, các bạn phải thêm Spring Webflux dependency để project có thể compile được:
|
1 2 3 4 |
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-webflux</artifactId> </dependency> |
