1科盛、 導(dǎo)包
<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(
"產(chǎn)品",
"產(chǎn)品接口文檔",
"產(chǎn)品接口文檔描述",
"/product/**");
}
/**
* 封裝了Docket的一些基本配置，創(chuàng)建多個(gè)Docket到Spring容器就可以實(shí)現(xiàn)分組
*/
private Docket basicDocket(String groupName, String title, String description, String path) {
// 創(chuàng)建全局參數(shù)
Parameter token = new ParameterBuilder()
.name("token")
.description("全局參數(shù)令牌")
// 參數(shù)數(shù)據(jù)類型
.modelRef(new ModelRef("String"))
// 參數(shù)類型（query/body/header）
.parameterType("header")
.build();
return new Docket(DocumentationType.SWAGGER_2)
// 是否啟用接口文檔，可以根據(jù)項(xiàng)目環(huán)境做調(diào)整
.enable(enable)
// 添加全局參數(shù)token
.globalOperationParameters(List.of(token))
// 分組名稱
.groupName(groupName)
// 接口文檔描述信息
.apiInfo(apiInfo(title, description))
// 如果接口用到這些參數(shù)，生成的接口文檔也會(huì)加入這些參數(shù)
// 該方法讓接口文檔過濾掉指定類型的參數(shù)遭京。
.ignoredParameterTypes(
HttpServletRequest.class,
HttpServletResponse.class
)
// 獲取ApiSelectorBuilder對象做一些過濾操作
.select()
// 只對指定的包生成接口文檔
// .apis(RequestHandlerSelectors.basePackage("com.cukiy.user.controller"))
// 只對帶有RestController注解的類生成接口文檔
// .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
// 只對Path符合規(guī)則的方法生成接口文檔,也可以把a(bǔ)nt換成regex
.paths(PathSelectors.ant(path))
// 過濾完成后轉(zhuǎn)為Docket返回
.build();
}
private ApiInfo apiInfo(String title, String description) {
return new ApiInfoBuilder()
// 接口文檔標(biāo)題
.title(title)
// 版本
.version("1.0.0")
// 描述
.description(description)
.build();
}
// 屬性填充完成之后調(diào)用該方法,需要實(shí)現(xiàn)InitializingBean
@Override
public void afterPropertiesSet() throws Exception {
// 配置了多套環(huán)境時(shí)，只在dev和test環(huán)境下啟用接口文檔
enable = environment.acceptsProfiles(Profiles.of("dev","test"));
}
}
3. 注解
Controller
@Api(tags = "用戶")
public class UserController {
@GetMapping("/queryById")
@ApiOperation(value = "根據(jù)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 = "響應(yīng)碼")
private Integer code;
@ApiModelProperty(value = "響應(yīng)信息")
private String msg;
@ApiModelProperty("響應(yīng)數(shù)據(jù)")
public T data;
}
public class UserVo {
@ApiModelProperty("用戶id")
private Long id;
@ApiModelProperty("昵稱 ")
private String nickname;
@ApiModelProperty("年齡")
private int age;
}
4. 備注
默認(rèn)文檔鏈接：項(xiàng)目地址/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.運(yùn)行效果
swagger01.png
