<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-ui -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-ui</artifactId>
<version>2.0.1</version>
</dependency>
package com.jiuding.util.config.swagger2;
import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* ${DESCRIPTION}
*
* @author edison
* @create 2017-01-02 23:53
*/
@EnableSwagger2
@Configuration
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//为当前包路径
.apis(RequestHandlerSelectors.any())
.paths(Predicates.not(PathSelectors.regex("/error.*")))//错误路径不监控
.build();
}
//构建 api文档的详细信息函数
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("功能测试")
//创建人
.contact(new Contact("tiger", "www.baidu.com", "[email protected]"))
//版本号
.version("2.0")
//描述
.description("API 描述")
.build();
}
}
访问:http://localhost:84/doc.html
1.概览
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧、轻量、并且功能强悍!
knife4j的前身是swagger-bootstrap-ui,为了契合微服务的架构发展,由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j。
更名后主要专注的方面
-
前后端Java代码以及前端Ui模块进行分离,在微服务架构下使用更加灵活
-
提供专注于Swagger的增强解决方案,不同于只是改善增强前端Ui部分
2.项目模块
目前主要的模块包括:
3.功能特性
简洁
基于左右菜单式的布局方式,是更符合国人的操作习惯吧,文档更清晰…
个性化配置
个性化配置项,支持接口地址、接口description属性、UI增强等个性化配置功能…
增强
接口排序、Swagger资源保护、导出Markdown、参数缓存众多强大功能…
4.业务场景
不使用增强功能,纯粹换一个swagger的前端皮肤
不使用增强功能,纯粹换一个swagger的前端皮肤。这种情况是最简单的,你项目结构下无需变更
可以直接引用swagger-bootstrap-ui的最后一个版本1.9.6或者使用knife4j-spring-ui
老版本引用
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
新版本引用
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-ui</artifactId>
<version>${lastVersion}</version>
</dependency>
Spring Boot项目单体架构使用增强功能
在Spring Boot单体架构下,knife4j提供了starter供开发者快速使用
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>${knife4j.version}</version>
</dependency>
该包会引用所有的knife4j提供的资源,包括前端Ui的jar包
Spring Cloud微服务架构
在Spring Cloud的微服务架构下,每个微服务其实并不需要引入前端的Ui资源,因此在每个微服务的Spring Boot项目下,引入knife4j提供的微服务starter
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-micro-spring-boot-starter</artifactId>
<version>${knife4j.version}</version>
</dependency>
在网关聚合文档服务下,可以再把前端的ui资源引入
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>${knife4j.version}</version>
</dependency>
5.界面效果
在线预览
http://knife4j.xiaominfo.com/doc.html
Authorize
Swagger Models
全局参数设置
离线文档下载
其他个性化设置
关键字搜索
6.总结
非常不错的一个开源项目,Gitee上已经有近2k的star,感兴趣的朋友不妨试试!
Github
https://github.com/xiaoymin/swagger-bootstrap-ui
码云
https://gitee.com/xiaoym/knife4j