一、介绍Knife4j
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。
参考文档
二、基础搭建
1、pom依赖
<io.swagger.version>1.5.21</io.swagger.version>
<swagger2.version>2.9.2</swagger2.version>
<knife4j.version>2.0.2</knife4j.version>
<!-- 引入 spring-boot -swagger 并生成优美的API文档 -->
<!-- swagger start -->
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>${io.swagger.version}</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>${io.swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger2.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger2.version}</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>${knife4j.version}</version>
</dependency>
<!-- swagger end -->
2、configuration
2.1、SwaggerProperties
@Data
@ConfigurationProperties(prefix = "swagger")
@Component
public class SwaggerProperties {
/**
* 是否启用
*/
private boolean enabled;
/**
* 标题
*/
private String title;
/**
* 文档描述
*/
private String description;
/**
* 项目路径
*/
private String termsOfServiceUrl;
/**
* 作者
*/
private String authorName;
/**
* 邮箱
*/
private String authorEmail;
/**
* 作者主页
*/
private String authorUrl;
/**
* 版本
*/
private String version;
/**
* web扫描的路径
*/
private String webBasePackage;
/**
* API扫描的路径
*/
private String apiBasePackage;
}
2.2、路径扫描配置InterceptorProperties
@Data
@ConfigurationProperties(prefix = "xiu-core.auth.interceptor")
@Component
public class InterceptorProperties {
/**
* 是否启用
*/
private boolean enable;
/**
* 包含的路径
*/
private String[] includePaths = new String[]{};
/**
* 排除路径
*/
private String[] excludePaths = new String[]{};
}
2.3、configuration配置SwaggerConfiguration
@Configuration
@EnableSwagger2
@EnableConfigurationProperties(value = SwaggerProperties.class)
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
@ConditionalOnProperty(value = {"swagger.enabled"}, matchIfMissing = true)
public class SwaggerConfiguration {
@Bean(value = "restWeb")
public Docket createRestWeb(SwaggerProperties swaggerProperties) {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(
new ApiInfoBuilder()
.title(swaggerProperties.getTitle())
.description(swaggerProperties.getDescription())
.termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl())
.contact(new Contact(swaggerProperties.getAuthorName(),
swaggerProperties.getAuthorUrl(),
swaggerProperties.getAuthorEmail()))
.version(swaggerProperties.getVersion())
.build()).groupName("后台 Web")
.select()
.apis(RequestHandlerSelectors.basePackage(swaggerProperties.getWebBasePackage()))
.paths(PathSelectors.any())
.build();
}
@Bean(value = "restApi")
public Docket createRestApi(SwaggerProperties swaggerProperties) {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(
new ApiInfoBuilder()
.title(swaggerProperties.getTitle())
.description(swaggerProperties.getDescription())
.termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl())
.contact(new Contact(swaggerProperties.getAuthorName(),
swaggerProperties.getAuthorUrl(),
swaggerProperties.getAuthorEmail()))
.version(swaggerProperties.getVersion())
.build()).groupName("前台 Api")
.select()
.apis(RequestHandlerSelectors.basePackage(swaggerProperties.getApiBasePackage()))
.paths(PathSelectors.any())
.build();
}
}
三、项目引用
3.1、配置项目属性
# Swagger配置
swagger:
enabled: true
title: 接口文档
description: 描述
termsOfServiceUrl: 地址
authorName: Mr.xiu
authorEmail: xdy_0722@sina.cn
authorUrl: 地址
version: 1.0.1
webBasePackage: com.xiu.lawyer.web.controller.admin
apiBasePackage: com.xiu.lawyer.web.controller.index
# knife开源的swagger ui配置
knife4j:
# 配置认证功能
basic:
# 是否开启认证
enable: true
# 用户名
username: admin
# 密码
password: 123456
3.2、拦截器及资源配置
/**
* 拦截器配置
*
* @param registry
*/
@Override
public void addInterceptors(InterceptorRegistry registry) {
//权限拦截器
if (interceptorConfig.isEnable()) {
registry.addInterceptor(authenticationInterceptor())
.addPathPatterns(interceptorConfig.getIncludePaths())
.excludePathPatterns(interceptorConfig.getExcludePaths());
}
}
/**
* 资源映射
*
* @param registry
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
if (swaggerProperties.isEnabled()) {
registry.addResourceHandler("doc.html","swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
四、页面展示
完!