JAVA SpringMVC老项目集成knife4j

需求: 原有一直使用showdoc工具对内或对外进行接口文档和功能的沟通，上层领导觉得人工进行手写

1. 浪费很多人工维护时间
2. 可能会做到接口更改而面对静态文档而更新不及时
3. showdoc的劣势是不能进行在线调试 需要辅助其他调试工具

但领导只需要类似swagger官方的页面即可。通过调研了解到knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案。

knife4j介绍:

Knife4j的前身是swagger-bootstrap-ui,前身swagger-bootstrap-ui是一个纯swagger-ui的ui皮肤项目

一开始项目初衷是为了写一个增强版本的swagger的前端ui,但是随着项目的发展,面对越来越多的个性化需求,不得不编写后端Java代码以满足新的需求,在swagger-bootstrap-ui的1.8.5~1.9.6版本之间,采用的是后端Java代码和Ui都混合在一个Jar包里面的方式提供给开发者使用.这种方式虽说对于集成swagger来说很方便,只需要引入jar包即可,但是在微服务架构下显得有些臃肿。

因此,项目正式更名为knife4j,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端Ui前端.

swagger-bootstrap-ui的所有特性都会集中在knife4j-spring-ui包中,并且后续也会满足开发者更多的个性化需求.

主要的变化是,项目的相关类包路径更换为com.github.xiaoymin.knife4j前缀,开发者使用增强注解时需要替换包路径

后端Java代码和ui包分离为多个模块的jar包,以面对在目前微服务架构下,更加方便的使用增强文档注解(使用SpringCloud微服务项目,只需要在网关层集成UI的jar包即可,因此分离前后端)

此次集成的是SSM的老项目，故中途关于查阅相关资料与测试使用了一些时间，不同与springboot或微服务集成，官网提供了相对完善的资料，此次是基于springMVC进行老版本(2.0.4)的集成工作。

一、

老项目是使用的Gradle构建工具,首先通过仓库查询到knife4j的依赖包，将以下两个包引入

 二、创建配置文件  SwaggerConfig

关键点说明:

1. .api是为了指定Controller扫描包路径
2. @ComponentScan 目的是为了使用knife4j增强功能，在2.0.4版本之前必须使用该写法，在2.0.5之后可以使用@EnableKnife4j

@EnableWebMvc
@EnableSwagger2
@Configuration
@ComponentScan(
		basePackages = {
				"com.github.xiaoymin.knife4j.spring.plugin",
				"com.github.xiaoymin.knife4j.spring.web"
		}
)
public class SwaggerConfig {

	@Bean
	public Docket defaultApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(groupApiInfo())
				.groupName("平台接口")
				.select()		                            
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
				.paths(PathSelectors.any())
				.build();
	}


	private ApiInfo groupApiInfo() {
		return new ApiInfoBuilder()
				.title("调试接口文档")
				.description("对外关键接口文档说明")
				.termsOfServiceUrl("http://www.group.com/")
				.contact("group@qq.com")
				.version("1.0")
				.build();
	}

}

**注意点: 区别于SpringBoot的注入,不使用@Configuration注解注入到Spring的IOC容器中,采用<bean>XML注入的方式注入到Spring的容器中

例如我的配置是: 

三、配置静态文件

由于knife4j是通过webjar的方式提供服务,因此对外访问的doc.html需要在我们的mvc环境中配置静态目录,否则会出现404，在spring.xml主容器的配置文件中配置

例如我的配置是:

另外这里需要注意的是: 需要在地址 <mvc:exclude-mapping path 中将上述地址排除，否则会跳转到默认页面中

另外需要在web.xml中进行配置:  添加部分servlet-mapping节点，添加这些节点是防止swagger的接口出现404的出现

四、基础配置已配置好，可以在需要的接口上进行注解的配置

1、首先在控制器的接口中添加@Api的注解 

2、在指定的接口上指定接口方法与接口参数等信息 例如:

 

五、完成基本的配置 可以尝试访问doc路径地址

 

剩下的工作即 将旧有的showdoc中的文档 一一对应的在系统中编写对应的接口进行迁移测试即可，当迁移测试完善完成后，即可舍弃旧有的文档工具。