swagger常用注解

swagger常用注解

@Api 用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源，使用方式：

@Api(value = "/pet", description = "Operations about pets")
public class PetController {
}

@ApiOperation：用在方法上，说明方法的作用，每一个url资源的定义,使用方式：

@RequestMapping(value = "/order/{orderId}", method = GET)
@ApiOperation(
    value = "Find purchase order by ID",
    notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
    response = Order.class,
    tags = { "Pet Store" })
public ResponseEntity<Order> getOrderById(@PathVariable("orderId") String orderId)
    throws NotFoundException {
    Order order = storeData.get(Long.valueOf(orderId));
    if (null != order) {
        return ok(order);
    } else {
        throw new NotFoundException(404, "Order not found");
    }
}

@ApiParam请求属性(我理解是方法请求里的属性),使用方式：

public ResponseEntity<Order> getOrderById (
    @ApiParam(value = "ID of pet that needs to be fetched", allowableValues = "range[1,5]", required = true)
    @PathVariable("orderId") 
    String orderId )

@ApiResponse：响应配置，使用方式：

@RequestMapping(value = "/order", method = POST)
@ApiOperation(value = "Place an order for a pet", response = Order.class)
@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
public ResponseEntity<String> placeOrder(
    @ApiParam(value = "order placed for purchasing the pet", required = true) Order order) {
    storeData.add(order);
    return ok("");
}

@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候；

@ApiModelProperty：描述一个model的属性。

@ApiModel("保养周期建议 response")
public class MaintenanceSuggestRequest implements Serializable {
    @ApiModelProperty("客户是否是否存在保养记录")
    private boolean existsMaintenance;
    @ApiModelProperty("保养周期建议")
    private String itemCode;//保养项编号
}