springboot+Swagger2构建API文档

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;  //设备告警时间
  
  //...
}

说明

  1. @Api(tags = "告警信息输出API")用在controller上,注解中还有produces、consumes、protocols、authorizations、hidden基本用不上,可按需使用。
  2. @ApiOperation,用在方法上,value-api名称,notes-api说明,其余属性一般都不用写。
  3. @ApiImplicitParams、@ApiImplicitParam配合用在方法上,用来说明请求参数。
  • 建议不要用使用@ApiParam,该注解功能与@ApiImplicitParam 相同,只是使用位置不同,@ApiImplicitParam写在方法上,@ApiParam加在参数上,后者会影响代码阅读,不如前者干净整洁。
  • @ApiImplicitParam必须用在@ApiImplicitParams里面,不然不起作用
  • @ApiImplicitParam属性:name-参数名,value-参数说明,required-是否必须,dataType数据类型(对象直接写类名)、paramType-参数类型(path-路径变量,query-问号拼接查询参数串,body-请求体,header-请求头,form-表单提交),这四个参数都不是必须的,有的能自动推断,有的有默认值,但是建议都写上,因为在某些场景下,自动推断会失效。
  1. @ApiIgnore,用在参数或者方法上,忽略该方法或者参数。此处有坑:如上示例所示,我是用一个对象接收参数,用@ApiImplicitParam依次描述各个参数,这时就必须使用@ApiIgnore忽略掉你的对象参数,不然swagger会将这个对象参数也推断为使用该api需要的参数。(当然你也可以不用对象接收参数,而是直接接收各个字段参数,这样swagger对参数的推断就与你使用@ApiImplicitParam声明的参数相符了)
  2. 当我们使用@RequestBody注解接收参数时,可以使用@ApiModel和@ApiModelProperty对该参数进行一些说明(不用也可以,swagger会自己推断一些信息。但是自动推断不能判断某个属性是不是必须的,这个必须你自己指定。另外,某些场景下自动推断会出错)
  3. @ApiResponses、@ApiResponse配合用在方法上或controller上。
  • 注意,这两个注解时用来说明可能出现的错误响应的,正确的响应在@ApiOperation中说明
  • @ApiResponse必须用在@ApiResponses中,不然无效
  • 用在方法优先级高于类上的
  • @ApiResponse属性:code-http响应码,message-消息,response-响应的数据类型
  • 一般不需要使用这两个注解,因为对API来说重要的是正确的响应是什么,错误的无需特别说明。

评论

暂无评论