Việc tích hợp Swagger UI vào dự án Spring Boot có thể gặp một số trở ngại, đặc biệt khi các hướng dẫn trên mạng có thể chưa cập nhật phiên bản mới nhất. Bài viết này sẽ hướng dẫn cách cấu hình Swagger UI với các phiên bản và thư viện mới hơn.

1. Thêm Thư viện Swagger vào Pom.xml

Đầu tiên, bạn cần thêm các dependency cần thiết vào file pom.xml của dự án. Phiên bản cũ hơn thường sử dụng springfox.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

Đảm bảo rằng dự án của bạn đã có dependency cơ bản cho web:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

2. Hiểu về Cấu trúc URL và Request Mapping

Khi gặp lỗi không truy cập được giao diện Swagger, hãy kiểm tra lại cấu trúc các @RequestMapping. Ví dụ, nếu bạn có:

• @RequestMapping("/hello") ở cấp class
• @RequestMapping(value = "/wo", method = RequestMethod.GET) ở cấp method

Thì địa chỉ truy cập sẽ là http://localhost:8080/hello/wo. Phần /hello được hiểu là thư mục cấp đầu tiên và /wo là thư mục con.

Nếu bạn đặt @RequestMapping("/") ở cấp class, nó sẽ là thư mục gốc. Khi đó, địa chỉ truy cập method có @RequestMapping("/wo") sẽ chỉ cần là http://localhost:8080/wo.

3. Nâng cấp và Xử lý Sự cố với Phiên bản Mới

Các phiên bản cũ của springfox có thể chứa lỗ hổng bảo mật. Việc nâng cấp lên phiên bản mới nhất, ví dụ 3.0.0, có thể gây ra lỗi và không truy cập được giao diện.

Một giải pháp thay thế hiệu quả và được cập nhật thường xuyên là sử dụng thư viện springdoc-openapi.

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

Sau khi thay đổi dependency, bạn cần khởi động lại ứng dụng Spring Boot để các thay đổi có hiệu lực.

4. Lưu ý về Annotations

Cần phân biệt rõ ràng giữa các annotation của springfox (như @Api) và springdoc. Khi sử dụng springdoc, bạn có thể cần loại bỏ các annotation không tương thích từ springfox, ví dụ như @Api trên các lớp controller kiểm thử.

Phiên bản mới nhất của Swagger UI có thể lên tới 5.10.3.

5. Cấu hình Đường dẫn Truy cập Swagger UI

Để có thể truy cập giao diện Swagger UI, bạn cần thêm một cấu hình vào file application.properties (hoặc application.yml):

springdoc.swagger-ui.path=/swagger-ui.html

Sau khi cấu hình này được thêm và ứng dụng khởi động lại, bạn có thể truy cập giao diện Swagger UI tại địa chỉ http://localhost:8080/swagger-ui.html.

Giao diện này sẽ hiển thị các API đã được định nghĩa trong dự án, bao gồm các phương thức GET, POST, PUT, DELETE cùng với các tham số tương ứng.