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 implements InitializingBean {
@Autowired
private Environment environment;
private Boolean enable;
@Bean
public Docket userDocket() {
return basicDocket(
"用户",
"用户接口文档",
"用户接口文档描述",
"/user/**");
}
@Bean
public Docket productDocket() {
return basicDocket(
"产品",
"产品接口文档",
"产品接口文档描述",
"/product/**");
}
/**
* 封装了Docket的一些基本配置，创建多个Docket到Spring容器就可以实现分组
*/
private Docket basicDocket(String groupName, String title, String description, String path) {
// 创建全局参数
Parameter token = new ParameterBuilder()
.name("token")
.description("全局参数令牌")
// 参数数据类型
.modelRef(new ModelRef("String"))
// 参数类型（query/body/header）
.parameterType("header")
.build();
return new Docket(DocumentationType.SWAGGER_2)
// 是否启用接口文档，可以根据项目环境做调整
.enable(enable)
// 添加全局参数token
.globalOperationParameters(List.of(token))
// 分组名称
.groupName(groupName)
// 接口文档描述信息
.apiInfo(apiInfo(title, description))
// 如果接口用到这些参数，生成的接口文档也会加入这些参数
// 该方法让接口文档过滤掉指定类型的参数。
.ignoredParameterTypes(
HttpServletRequest.class,
HttpServletResponse.class
)
// 获取ApiSelectorBuilder对象做一些过滤操作
.select()
// 只对指定的包生成接口文档
// .apis(RequestHandlerSelectors.basePackage("com.cukiy.user.controller"))
// 只对带有RestController注解的类生成接口文档
// .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
// 只对Path符合规则的方法生成接口文档,也可以把ant换成regex
.paths(PathSelectors.ant(path))
// 过滤完成后转为Docket返回
.build();
}
private ApiInfo apiInfo(String title, String description) {
return new ApiInfoBuilder()
// 接口文档标题
.title(title)
// 版本
.version("1.0.0")
// 描述
.description(description)
.build();
}
// 属性填充完成之后调用该方法,需要实现InitializingBean
@Override
public void afterPropertiesSet() throws Exception {
// 配置了多套环境时，只在dev和test环境下启用接口文档
enable = environment.acceptsProfiles(Profiles.of("dev","test"));
}
}
3. 注解
Controller
@Api(tags = "用户")
public class UserController {
@GetMapping("/queryById")
@ApiOperation(value = "根据ID查询用户", notes = "ID不能为空")
@ApiResponses({
@ApiResponse(code = 200, message = "请求成功")
})
public DataJsonVo<UserVo> queryById(
@ApiParam(value = "用户ID", required = true)
@RequestParam
Long id) {
}
}
VO
public class DataJsonVo<T> {
@ApiModelProperty(value = "响应码")
private Integer code;
@ApiModelProperty(value = "响应信息")
private String msg;
@ApiModelProperty("响应数据")
public T data;
}
public class UserVo {
@ApiModelProperty("用户id")
private Long id;
@ApiModelProperty("昵称 ")
private String nickname;
@ApiModelProperty("年龄")
private int age;
}
4. 备注
默认文档链接：项目地址/swagger-ui.html
如果使用了Shiro，需要开放以下接口
filterChain.put("/swagger-ui.html", "anon");
filterChain.put("/favicon.ico", "anon");
filterChain.put("/webjars/**", "anon");
filterChain.put("/swagger-resources/**", "anon");
filterChain.put("/v2/**", "anon");
5.运行效果
swagger01.png
