Cài đặt Swagger với SpringFox

Để tích hợp Swagger vào dự án Maven, bạn cần thêm các dependency sau:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.5.0</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.5.0</version>
</dependency>

Định nghĩa API với @API

Annotation @API dùng để khai báo một API trong Swagger. Bạn có thể sử dụng thuộc tính description để mô tả chức năng của API.

@API(value = "Quản lý người dùng", description = "Các dịch vụ liên quan đến quản lý tài khoản người dùng")

Bên cạnh thuộc tính description và value, @API còn có các thuộc tính tùy chọn:

Định nghĩa phương thức với @ApiOperation

Mỗi API có thể chứa nhiều phương thức được định nghĩa bởi @ApiOperation. Annotation này cho phép bạn:

• Sử dụng value và notes để mô tả chức năng của phương thức
• Sử dụng @ApiParam để mô tả tham số đầu vào
• Chỉ định loại trả về với response
• Cần chú ý phải chỉ định method trong @RequestMapping

@ApiOperation(value = "Đăng nhập người dùng", 
              notes = "Phương thức này cho phép người dùng đăng nhập vào hệ thống",
              response = User.class,
              httpMethod = "POST")

Các thuộc tính tùy chọn của @ApiOperation:

Mô tả tham số với @ApiParam

Đối với các tham số đơn giản:

@ApiParam(value = "ID người dùng", required = true) String userId

Đối với các tham số phức tạp, cần định nghĩa @ApiModel và @ApiModelProperty trong lớp:

@ApiModel(description = "Đối tượng yêu cầu chung")
public class GeneralRequestVO {
    @ApiModelProperty(value = "Thông điệp yêu cầu", required = true)
    private String message;
    
    // các thuộc tính khác
}

Các thuộc tính tùy chọn của @ApiParam:

Định nghĩa giá trị trả về

Đối với các lớp trả về, cần định nghĩa @ApiModel và @ApiModelProperty tương tự như @ApiParam. Ngoài ra, có thể sử dụng @ApiResponses để định nghĩa các mã lỗi:

@ApiResponses(value = {
    @ApiResponse(code = 200, message = "Thành công"),
    @ApiResponse(code = 400, message = "Yêu cầu không hợp lệ"),
    @ApiResponse(code = 404, message = "Không tìm thấy tài nguyên")
})

Tổng quan các annotation Swagger

Chi tiết các annotation

@Api

Được sử dụng để khai báo tài nguyên API Swagger. Nó ảnh hưởng đến cả Resource Listing và API Declaration.

@Path("/san-pham") 
@Api(value = "/san-pham", description = "Các thao tác liên quan đến sản phẩm")
@Produces({"application/json", "application/xml"}) 
public class ProductResource { ... }

@ApiOperation

Được sử dụng để khai báo một operation trong tài nguyên API.

@GET
@Path("/tim-kiem")
@ApiOperation(value = "Tìm kiếm sản phẩm", 
            notes = "Tìm kiếm sản phẩm theo nhiều tiêu chí",
            response = Product.class,
            responseContainer = "List")
public Response searchProducts(...) { ... }

@ApiResponses và @ApiResponse

Dùng để mô tả các mã trạng thái HTTP trả về.

@ApiResponses(value = { 
    @ApiResponse(code = 400, message = "ID không hợp lệ"),
    @ApiResponse(code = 404, message = "Sản phẩm không tồn tại")
})

@ApiParam

Dùng để thêm metadata cho các tham số của phương thức.

@Path("/{id}")
@ApiOperation(value = "Cập nhật sản phẩm")
public Response updateProduct(
    @ApiParam(value = "ID sản phẩm cần cập nhật", required = true) @PathParam("id") String id,
    @ApiParam(value = "Đối tượng sản phẩm cập nhật", required = true) Product product) { ... }

@ApiModel và @ApiModelProperty

Dùng để mô tả các model trong API.

@ApiModel(value="ProductModel", description="Mô hình sản phẩm")
public class Product {
    @ApiModelProperty(value = "Trạng thái sản phẩm", allowableValues = "còn_hàng,hết_hàng")
    private String status;
    
    // các thuộc tính khác
}