Swagger2笔记

配置

很简单，如下所示：

1@Configuration
2@EnableSwagger2
3public class SwaggerConfig {
4
5  @Bean
6  public Docket createRestApi(){
7    return new Docket(DocumentationType.SWAGGER_2)
8      .apiInfo(apiInfo())
9      .select()
10      .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
11      .paths(PathSelectors.any())
12      .build();
13  }
14
15  private ApiInfo apiInfo(){
16    return new ApiInfoBuilder().title("doris-alarm-service")
17      .description("告警服务API")
18      .termsOfServiceUrl("http://192.168.7.56/")
19      .contact(new Contact("王用军","","wangyongjun@sunseaiot.com"))
20      .version("0.1")
21      .build();
22  }
23
24}
25

使用

1@RestController
2@Api(tags = {"告警输入API"})
3public class AlarmInputController {
4
5  @Autowired
6  private AlarmService alarmService;
7
8  @PostMapping(value = "/alarm")
9  @ApiOperation(value = "创建一个告警",notes = "向服务器发送一个告警")
10  @ApiImplicitParams(@ApiImplicitParam(name = "alarmCreate",value = "创建告警信息实体", required = true,dataType = "AlarmCreate",paramType = "body"))
11  public ResponseEntity<Alarm> createAlarm(
12   @RequestBody AlarmCreate alarmCreate
13  ){
14    return new ResponseEntity<>(alarmService.createAlarm(alarmCreate), HttpStatus.CREATED);
15  }
16
17}
18
19/**
20 * 根据告警信息uuid获取告警信息
21 * @param uuid
22 * @return
23 */
24@GetMapping(value = "/alarm/{uuid}")
25@ApiOperation(value = "根据uuid获取一条告警",notes = "通过uuid获取一条告警信息")
26@ApiImplicitParams(@ApiImplicitParam(name = "uuid",value = "告警信息编号",required = true,dataType = "Long",paramType = "path"))
27public ResponseEntity<Alarm> getByLevel(@PathVariable(value = "uuid") Long uuid){
28  if(uuid == null){
29    ResponseEntity.badRequest().body(Result.failure401().msg("参数uuid不能为null"));
30  }
31  return new ResponseEntity<>(alarmService.getAlarmByUuid(uuid), HttpStatus.OK);
32}
33
34/**
35 * 多条告警信息
36 */
37@GetMapping(value = "/alarms")
38@ApiOperation(value = "根据条件获取多条告警",notes = "通过条件获取多条告警信息")
39@ApiImplicitParams({
40  @ApiImplicitParam(name = "serialNum", value = "设备对告警信息的编号", required = false, dataType = "string",paramType = "query"),
41  @ApiImplicitParam(name = "name", value = "告警名称", required = false, dataType = "string",paramType = "query"),
42  @ApiImplicitParam(name = "value", value = "告警值", required = false, dataType = "string",paramType = "query"),
43  @ApiImplicitParam(name = "dsn", value = "告警设备DSN", required = false, dataType = "string",paramType = "query"),
44  @ApiImplicitParam(name = "level", value = "告警级别，WARN，SERIOUS，ERROR", required = false, dataType = "string",paramType = "query"),
45  @ApiImplicitParam(name = "alarmTimeStart", value = "设备告警时间范围开始", required = false,dataType = "long",paramType = "query"),
46  @ApiImplicitParam(name = "alarmTimeEnd", value = "设备告警时间范围结束", required = false, dataType = "long",paramType = "query"),
47})
48public ResponseEntity<List<Alarm>> getAlarms(@ApiIgnore AlarmSearch alarmSearch){
49
50  return new ResponseEntity<>(alarmService.getAlarms(alarmSearch),HttpStatus.OK);
51}
52
53@ApiModel
54public class AlarmCreate implements Serializable {
55
56  private String serialNum;  //设备对告警信息的编号
57  @ApiModelProperty(value = "告警名称",dataType = "string",required = true)
58  private String name;  //告警名称
59  @ApiModelProperty(value = "告警值",dataType = "string",required = true)
60  private String value;  //告警值
61  @ApiModelProperty(value = "告警设备DSN",dataType = "string",required = true)
62  private String dsn;  //告警设备DSN
63  @ApiModelProperty(value = "告警等级",dataType = "string",required = true)
64  private String level; //告警级别，WARN，SERIOUS，ERROR
65  @ApiModelProperty(value = "设备告警时间",dataType = "long",required = true)
66  private Long alarmTime;  //设备告警时间
67  
68  //...
69}
70

说明

@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上。

注意，这两个注解时用来说明可能出现的错误响应的，正确的响应在@ApiOperation中说明
@ApiResponse必须用在@ApiResponses中，不然无效
用在方法优先级高于类上的
@ApiResponse属性：code-http响应码，message-消息，response-响应的数据类型
一般不需要使用这两个注解，因为对API来说重要的是正确的响应是什么，错误的无需特别说明。

springboot+Swagger2构建API文档

Swagger2笔记

配置

使用

说明

评论区

相关推荐