Tạo RESTful API document sử dụng Springfox cho Swagger trong Spring Boot

Giống như RAML, Swagger specification hay còn gọi là OpenAPI specification là một đặc tả dùng để định nghĩa các API của RESTful Web Service. Springfox là một thư viện được sử dụng để tạo ra các RESTful API document trong Spring, implement Swagger specification. Trong bài viết này, chúng ta hãy cùng nhau tìm hiểu cách tạo RESTful API document sử dụng Springfox cho Swagger trong Spring Boot các bạn nhé!

Đầu tiên, chúng ta cần một Spring Boot project để làm ví dụ:

Tạo RESTful API document sử dụng Springfox cho Swagger trong Spring Boot

Để làm việc với Springfox cho Spring Boot, các bạn chỉ cần thêm springfox-boot-starter dependency như sau:

Giả sử bây giờ mình có một controller định nghĩa một API để quản lý thông tin sinh viên đơn giản

Tạo RESTful API document sử dụng Springfox cho Swagger trong Spring Boot

như sau:

Mặc định, nếu bây giờ các bạn chạy ứng dụng Spring Boot này lên rồi truy cập tới địa chỉ http://localhost:8080/swagger-ui/index.html, các bạn sẽ thấy kết quả như sau:

Tạo RESTful API document sử dụng Springfox cho Swagger trong Spring Boot

Như các bạn thấy, mặc định Springfox sẽ scan hết tất cả các controller có trong ứng dụng của chúng ta để generate document cho những API được định nghĩa. BasicErrorController là controller có sẵn của Spring Boot còn StudentController là controller mà mình đang định nghĩa.

Để custom controller nào, request URL nào sẽ được Springfox generate RESTful API document, các bạn có thể định nghĩa bean của class Docket của Springfox. Springfox Docket là một đối tượng dùng để cấu hình cho việc tạo RESTful API document sử dụng Springfox sẽ như thế nào?

Cho ví dụ này, mình sẽ thêm cấu hình cho class Springfox Docket như sau:

Ở đây, mình định nghĩa Docket với OpenAPI specification 3.0.

Phương thức select() trả về cho chúng ta đối tượng ApiSelectorBuilder, giúp chúng ta có thể sử dụng đối tượng ApiSelectorBuilder này với các phương thức apis() và paths() để filter những controller nào, những phương thức nào cần được sử dụng để tạo RESTful API document.

Như các bạn thấy, trong phương thức path(), mình đã sử dụng đối tượng PathSelectors với phương thức regex() để filter việc tạo RESTful document chỉ cho request URL “/student”.

Bây giờ, nếu các bạn chạy lại ứng dụng Spring Boot này và request tới URL http://localhost:8080/swagger-ui/index.html, các bạn sẽ thấy kết quả như sau:

Tạo RESTful API document sử dụng Springfox cho Swagger trong Spring Boot

Như các bạn thấy, ở đây Springfox chỉ tạo một document với thông tin về StudentController của chúng ta.

Nếu các bạn click vào request GET “/student/findById” của student-controller thì các bạn sẽ thấy kết quả như sau:

Tạo RESTful API document sử dụng Springfox cho Swagger trong Spring Boot

Như các bạn thấy Springfox đã sử dụng một số các giá trị mặc định để tạo document cho StudentController của chúng ta theo chuẩn của Swagger.

Ngoài những giá trị mặc định mà Springfox đã generate, Springfox còn hỗ trợ cho phép chúng ta còn có thể customize RESTful API document của chúng ta.

Chúng ta có thể thêm một số thông tin khác về các API của chúng ta, ví dụ như thông tin về thông tin liên lạc như sau:

Trong ví dụ trên, mình đã thêm một số thông tin như title, description và contact cho document của chúng ta.

Kết quả:

Tạo RESTful API document sử dụng Springfox cho Swagger trong Spring Boot

Chúng ta còn có thể customize document cho các API bằng cách thêm một số description về nó, các dữ liệu trả về.

Chúng ta làm điều này bằng cách modify StudentController sử dụng các annotation @ApiOperation, @ApiResponse của Swagger, ví dụ như sau:

Kết quả:

Tạo RESTful API document sử dụng Springfox cho Swagger trong Spring Boot

Tạo RESTful API document sử dụng Springfox cho Swagger trong Spring Boot

4.5/5 - (2 bình chọn)

Add Comment