一、接口文档生成工具
使用的工具knife4j
采用的版本:
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>
由于采用openAPI3.0的注解,所以才使用3.x的版本。访问/v2/api-docs,/v3/api-docs,或者/doc.html都能看到接口信息,对外暴露具有风险
二、问题
区别生产环境和开发环境,开发环境可以展示接口文档,但是生产环境不用展示接口文档,因此需要有一个开关控制接口文档的生成与否。
三、解决方法
1、使用@Conditional注解
由于knife4j的使用需要配置SwaggerConfig类,如果不配置这个类到spring管理,是不是就能达到将文档功能取消的目的,因此想到条件注解。
条件注解:
@Conditional是Spring4新提供的注解,它的作用是根据某个条件创建特定的Bean,通过实现Condition接口,并重写matches接口来构造判断条件。总的来说,就是根据特定条件来控制Bean的创建行为,这样我们可以利用这个特性进行一些自动的配置。
使用上有:
- @ConditionalOnProperty 应用环境中的属性满足条件生效
- @ConditionalOnBean Spring容器中存在对应的实例生效
- @ConditionalOnMissingBean Spring容器中不存在对应的实例生效
- @ConditionalOnExpression 判断SpEL 表达式成立生效
使用@ConditionalOnExpression注解在swagger的配置类上,然后在application.properties中定义一个key-value对,在profile中控制value的值,从而达到开关的目的。
但实际验证中这种方法并没有效果,无法达到去除doc.html内容的目的,访问url :/v2/api-docs,/v3/api-docs依然能看到接口文档的json串
这里引出一个猜想:
- 猜测存在一种自动机制,能够自动生成接口文档,而并不需要配置类。即使不配置swaggerConfig类,一样能产生接口文档。
2、knife4j官方给的解决办法
在application.properties中设置
# 开启文档屏蔽
knife4j.production=true
不起作用
3、能work的解决办法
springfox也存在一个开关,在application.properties中设置
springfox.documentation.auto-startup=false
证明猜想,确实存在一种自动机制,自动扫描,生成接口的json串。将这个开关关闭就不会产生接口的json串。
=分割线=
另外由于有一个swagger的config路径在上述操作屏蔽后,依然能够访问,具体路径为(/swagger-resources/configuration/ui)
如果你不想要这个config路径能够访问到,也可以进一步屏蔽:
# 屏蔽 /swagger-resources/configuration/ui
# 在application.properties中设置
springfox.documentation.enabled=false
并且配合条件注解,将条件注解也加到对应的SwaggerConfig类上:
@ConditionalOnProperty(name = "springfox.documentation.auto-startup", havingValue = "true")
public class SwaggerConfig {
/**
具体代码
*/
}
这样SwaggerConfig类在springfox.documentation.auto-startup = true就不被spring容器管理,相当于注释了这个类。