需求: 原有一直使用showdoc工具对内或对外进行接口文档和功能的沟通,上层领导觉得人工进行手写
- 浪费很多人工维护时间
- 可能会做到接口更改而面对静态文档而更新不及时
- 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
关键点说明:
- .api是为了指定Controller扫描包路径
- @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中的文档 一一对应的在系统中编写对应的接口进行迁移测试即可,当迁移测试完善完成后,即可舍弃旧有的文档工具。