1、导包
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2、配置类
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
// 是否启用swagger
.enable(true)
// swagger信息
.apiInfo(apiInfo())
.select()
// swagger要扫描的包路径
.apis(RequestHandlerSelectors.basePackage("com.haiot.dm.controller"))
// 扫描过滤规则
.paths(PathSelectors.any())
.build();
}
// api文档的详细信息函数
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 页面标题
.title("SpringBoot 集成 Swagger")
//描述
.description("用于测试 SpringBoot 集成 Swagger")
//版本号
.version("1.0")
.build();
}
}
3、使用@EnableSwagger2注解修饰启动类
4、使用注解修饰controller层以及其中的方法,常用注解如下:
- @Api:作用在类上,用于说明该类的作用。通常标记一个Controller类作为Swagger文档资源。
@RestController
@Api(tags="管理端-设备消息管理")
public class MessageController {
}
- @ApiOperation:作用在方法上,用于说明该方法的作用。通常用于标记Controller中的方法。
@ApiOperation("删除一条事件")
@GetMapping("deleteOneMsg")
public ServerResponse deleteOneMsg(Integer eventId) {
}
- @ApiImplicitParams:作用在方法上,包含一组参数的说明,用于说明接口请求参数的意义。
- @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面 。
- paramType:参数放在哪个地方
- name:参数代表的含义
- value:参数名称
- dataType:参数类型
- required:是否必要,默认false
- defaultValue:参数的默认值
@ApiOperation(value = "发送简单邮件")
@GetMapping("sendSimpleMail")
@ApiImplicitParams({
@ApiImplicitParam(name = "to", value = "收件人"),
@ApiImplicitParam(name = "subject", value = "邮件主题"),
@ApiImplicitParam(name = "text", value = "邮件内容")
})
private void sendSimpleMail(String to, String subject, String text) throws AddressException {
emailService.sendSimpleMail(to, subject, text);
}
- @ApiModel:作用在实体类上,用于描述一个Model的信息。这个注解一般用在post请求时,因参数被@RequestBody修饰,请求参数无法使用@ApiImplicitParam注解进行描述的时候;
- @ApiModelProperty:作用在实体类的属性上,用于描述model的某个属性。
@Data
@ApiModel
public class MailMessageVO {
@ApiModelProperty(value = "收件人")
private String to; // 收件人
@ApiModelProperty(value = "主题")
private String subject; // 主题
@ApiModelProperty(value = "项目名")
private String projectName; // 项目名
@ApiModelProperty(value = "事项类型")
private String eventItemType; // 事项类型
@ApiModelProperty(value = "报错位置")
private String errorPosition; // 报错位置
@ApiModelProperty(value = "报错原因")
private String errorReason; // 报错原因
@ApiModelProperty(value = "报错描述")
private String errorDescribe; // 报错描述
}
5、 遇到的小坑之swagger页面资源读取不到?
看了好久博客说,需要配置过滤器,允许swagger-ui资源被读取,但还是没有用。
离谱的是,前一天配置了swagger2.9.2与springboot2.5.6死活从swagger2.5.0版本变不过来,明明依赖已经刷新了,显示的也是2.9.2,就算配置了过滤器也无法正常展示,但是关机之后第二天重新启动项目就没有问题了。 想看看是否是过滤器起了作用,所以注释了过滤器类,但是效果依然在,那为什么昨天就不行呢?万能的重启大法啊!
所以之后配置swagger2.9.2再遇到这种问题的话,可以这么解决:
1、关机,重新启动项目(关掉idea似乎不太行),不行的话换下面的方法
2、配置过滤器类,然后重新启动项目,如果没有生效,则关机再重新启动项目
@Configuration
public class Config extends WebMvcConfigurationSupport {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**").addResourceLocations(
"classpath:/static/");
registry.addResourceHandler("swagger-ui.html").addResourceLocations(
"classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations(
"classpath:/META-INF/resources/webjars/");
super.addResourceHandlers(registry);
}
}