Swagger2笔记

配置

很简单，如下所示：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

  @Bean
  public Docket createRestApi(){
    return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()
      .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
      .paths(PathSelectors.any())
      .build();
  }

  private ApiInfo apiInfo(){
    return new ApiInfoBuilder().title("doris-alarm-service")
      .description("告警服务API")
      .termsOfServiceUrl("http://192.168.7.56/")
      .contact(new Contact("王用军","","wangyongjun@sunseaiot.com"))
      .version("0.1")
      .build();
  }

}

使用

@RestController
@Api(tags = {"告警输入API"})
public class AlarmInputController {

  @Autowired
  private AlarmService alarmService;

  @PostMapping(value = "/alarm")
  @ApiOperation(value = "创建一个告警",notes = "向服务器发送一个告警")
  @ApiImplicitParams(@ApiImplicitParam(name = "alarmCreate",value = "创建告警信息实体", required = true,dataType = "AlarmCreate",paramType = "body"))
  public ResponseEntity<Alarm> createAlarm(
   @RequestBody AlarmCreate alarmCreate
  ){
    return new ResponseEntity<>(alarmService.createAlarm(alarmCreate), HttpStatus.CREATED);
  }

}

/**
 * 根据告警信息uuid获取告警信息
 * @param uuid
 * @return
 */
@GetMapping(value = "/alarm/{uuid}")
@ApiOperation(value = "根据uuid获取一条告警",notes = "通过uuid获取一条告警信息")
@ApiImplicitParams(@ApiImplicitParam(name = "uuid",value = "告警信息编号",required = true,dataType = "Long",paramType = "path"))
public ResponseEntity<Alarm> getByLevel(@PathVariable(value = "uuid") Long uuid){
  if(uuid == null){
    ResponseEntity.badRequest().body(Result.failure401().msg("参数uuid不能为null"));
  }
  return new ResponseEntity<>(alarmService.getAlarmByUuid(uuid), HttpStatus.OK);
}

/**
 * 多条告警信息
 */
@GetMapping(value = "/alarms")
@ApiOperation(value = "根据条件获取多条告警",notes = "通过条件获取多条告警信息")
@ApiImplicitParams({
  @ApiImplicitParam(name = "serialNum", value = "设备对告警信息的编号", required = false, dataType = "string",paramType = "query"),
  @ApiImplicitParam(name = "name", value = "告警名称", required = false, dataType = "string",paramType = "query"),
  @ApiImplicitParam(name = "value", value = "告警值", required = false, dataType = "string",paramType = "query"),
  @ApiImplicitParam(name = "dsn", value = "告警设备DSN", required = false, dataType = "string",paramType = "query"),
  @ApiImplicitParam(name = "level", value = "告警级别，WARN，SERIOUS，ERROR", required = false, dataType = "string",paramType = "query"),
  @ApiImplicitParam(name = "alarmTimeStart", value = "设备告警时间范围开始", required = false,dataType = "long",paramType = "query"),
  @ApiImplicitParam(name = "alarmTimeEnd", value = "设备告警时间范围结束", required = false, dataType = "long",paramType = "query"),
})
public ResponseEntity<List<Alarm>> getAlarms(@ApiIgnore AlarmSearch alarmSearch){

  return new ResponseEntity<>(alarmService.getAlarms(alarmSearch),HttpStatus.OK);
}

@ApiModel
public class AlarmCreate implements Serializable {

  private String serialNum;  //设备对告警信息的编号
  @ApiModelProperty(value = "告警名称",dataType = "string",required = true)
  private String name;  //告警名称
  @ApiModelProperty(value = "告警值",dataType = "string",required = true)
  private String value;  //告警值
  @ApiModelProperty(value = "告警设备DSN",dataType = "string",required = true)
  private String dsn;  //告警设备DSN
  @ApiModelProperty(value = "告警等级",dataType = "string",required = true)
  private String level; //告警级别，WARN，SERIOUS，ERROR
  @ApiModelProperty(value = "设备告警时间",dataType = "long",required = true)
  private Long alarmTime;  //设备告警时间
  
  //...
}

说明

@Api(tags = "告警信息输出API")用在controller上，注解中还有produces、consumes、protocols、authorizations、hidden基本用不上，可按需使用。
@ApiOperation，用在方法上，value-api名称，notes-api说明，其余属性一般都不用写。
@ApiImplicitParams、@ApiImplicitParam配合用在方法上，用来说明请求参数。

建议不要用使用@ApiParam，该注解功能与@ApiImplicitParam 相同，只是使用位置不同，@ApiImplicitParam写在方法上，@ApiParam加在参数上，后者会影响代码阅读，不如前者干净整洁。
@ApiImplicitParam必须用在@ApiImplicitParams里面，不然不起作用
@ApiImplicitParam属性：name-参数名，value-参数说明，required-是否必须，dataType数据类型（对象直接写类名）、paramType-参数类型（path-路径变量，query-问号拼接查询参数串，body-请求体，header-请求头，form-表单提交），这四个参数都不是必须的，有的能自动推断，有的有默认值，但是建议都写上，因为在某些场景下，自动推断会失效。

@ApiIgnore，用在参数或者方法上，忽略该方法或者参数。此处有坑：如上示例所示，我是用一个对象接收参数，用@ApiImplicitParam依次描述各个参数，这时就必须使用@ApiIgnore忽略掉你的对象参数，不然swagger会将这个对象参数也推断为使用该api需要的参数。（当然你也可以不用对象接收参数，而是直接接收各个字段参数，这样swagger对参数的推断就与你使用@ApiImplicitParam声明的参数相符了）
当我们使用@RequestBody注解接收参数时，可以使用@ApiModel和@ApiModelProperty对该参数进行一些说明（不用也可以，swagger会自己推断一些信息。但是自动推断不能判断某个属性是不是必须的，这个必须你自己指定。另外，某些场景下自动推断会出错）
@ApiResponses、@ApiResponse配合用在方法上或controller上。