一、swagger常用注解
1、与模型相关的注解
两个注解：
- @ApiModel：用在模型类上，对模型类做注释；
- @ApiModelProperty：用在属性上，对属性做注释
2、与接口相关的注解
六个注解：
- @Api：用在controller上，对controller进行注释；
- @ApiOperation：用在API方法上，对该API做注释，说明API的作用；
- @ApiImplicitParams：用来包含API的一组参数注解，可以简单的理解为参数注解的集合声明；
- @ApiImplicitParam：用在@ApiImplicitParams注解中，也可以单独使用，说明一个请求参数的各个方面，该注解包含的常用选项有：
- paramType：参数所放置的地方，包含query、header、path、body以及form，最常用的是前四个。
- name：参数名；
- dataType：参数类型，可以是基础数据类型，也可以是一个class；
- required：参数是否必须传；
- value：参数的注释，说明参数的意义；
- defaultValue：参数的默认值；
- @ApiResponses：通常用来包含接口的一组响应注解，可以简单的理解为响应注解的集合声明；
- @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
- code：即httpCode，例如400
- message：信息，例如"请求参数没填好"
- @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候） @ApiModelProperty：描述一个model的属性
二、几个注意点：
- 为了在swagger-ui上看到输出，至少需要两个注解：@Api和@ApiOperation
- 即使只有一个@ApiResponse，也需要使用@ApiResponses包住
- 对于@ApiImplicitParam的paramType：query、form域中的值需要使用@RequestParam获取， header域中的值需要使用@RequestHeader来获取，path域中的值需要使用@PathVariable来获取，body域中的值使用@RequestBody来获取，否则可能出错；而且如果paramType是body，name就不能是body，否则有问题，与官方文档中的“If paramType is "body", the name should be "body"不符。例如 @RestController
@RequestMapping("/api/house")
@Api(tags = "房屋相关接口")
public class HouseController { @ApiOperation("房屋信息统计")
@ApiImplicitParams({ @ApiImplicitParam(name = "city", value = "城市", required = true, paramType = "form") })
@PostMapping("/houseCount")
public HouseCountView houseCount(@RequestParam("city") String city) {
HouseCountView hcv = new HouseCountView();
Map<String, Object> mapNewHomes = new HashMap<>();
mapNewHomes.put("city", city);
Map<String, Object> mapSecondHand = new HashMap<>();
mapSecondHand.put("city", city);
RentalApply rentalApply = new RentalApply();
rentalApply.setCity(city);
hcv.setNewHouse(newHomesService.count(mapNewHomes));
hcv.setSecond(secondHandService.count(mapSecondHand));
hcv.setRenting(rentalApplyService.count(rentalApply));
return hcv;
} }