写在前面
springboot下的API文档提供方式有很多种，用的最广泛的还是Swagger。本文不讨论不同方式的API文档提供优缺点，只是介绍一个做的比较不错的Swagger下的开源项目knife4j。跟这个项目很有缘，早在很多年前就使用过它的前身swagger-bootstrap-ui。- knife4j文档是非常清晰的，对初学者非常友好，但对某些使用情况说明还缺乏整体连贯性，导致需要额外的调试才能满足某些需求。下面是我对其
demo做的一个整体记录
Spring Boot下集成knife4j
注意：
- 我这里的涉及到的示例代码是
kotlin,大家自行转换到java即可。 - 我用的是
knife4j-spring-boot-starter，纯knife4j的方式手动写一下配置类即可，参照knife4j文档
一、引用依赖
在build.gradle.kts文件（对应maven下pom.xml）中增加
implementation("com.github.xiaoymin:knife4j-spring-boot-starter:3.0.3")
二、建立Spring SPI文件
- 文件路径（没有就新建，有就在文件中新增文件内容）：
resources -> META-INF -> spring.factories - 文件内容
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.github.xiaoymin.knife4j.spring.configuration.Knife4jAutoConfiguration
三、建立Spring SwaggerConfiguration文件
注意：我用的注解都是必须的，不能减少；但是可以在其他类中申明一些，这里就可以减少一些
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j
import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.beans.factory.annotation.Value
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.context.annotation.Import
import org.springframework.web.servlet.config.annotation.EnableWebMvc
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration
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
@Configuration
@EnableWebMvc
@EnableSwagger2
@EnableKnife4j
@Import(value = [BeanValidatorPluginsConfiguration::class])
class SwaggerConfiguration
@Autowired
constructor(
private val openApiExtensionResolver: OpenApiExtensionResolver
) {
@Value("\${server.port}")
private val serverPort: String? = null
@Value("\${info.domain}")
private val domain: String? = null
@Bean(value = ["defaultApi"])
fun defaultApi(): Docket {
val groupName = "1.0 版本"
return Docket(DocumentationType.OAS_30)
.host("${domain}:${serverPort}")
.apiInfo(apiInfo())
.groupName(groupName)
.select()
.apis(RequestHandlerSelectors.basePackage("这里替换成你的controllers包路径"))
.paths(PathSelectors.any())
.build() //赋予插件体系
.extensions(openApiExtensionResolver.buildSettingExtensions())
}
fun apiInfo(): ApiInfo {
return ApiInfoBuilder()
.description("xxx相关API")
.title("xxx-api")
.version("1.0")
.termsOfServiceUrl("http://${domain}:${serverPort}")
.contact(Contact("lc", "http://xxx.com", "xxx@xx.com"))
.build()
}
}
四、重写Spring WebMvcConfigurer#addResourceHandlers方法，放过knife4j资源文件
@SpringBootApplication
class DemoApplication : WebMvcConfigurer, CommandLineRunner {
override fun addResourceHandlers(registry: ResourceHandlerRegistry) {
registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
五、配置application.yml，加入knife4j配置
knife4j:
enable: true # 启用 knife4j
setting:
enableFooter: false # 是否启用Footer
enableFooterCustom: true # 是否自定义Footer-自定义时enableFooter要为false
footerCustomContent: 你的公司名称
production: false # 是否是生产环境-生产环境会关闭api功能
basic:
enable: true # 开启basic认证
username: test
password: 12313
# 自定义
info:
domain: localhost # 自定义的hosts，去掉的话就相应的把`SwaggerConfiguration`代码中的`host`去掉就行了
API文档访问：http://localhost:8080
到这里全部完成了，剩下的操作与正常的Swagger操作一致，更多详细信息请参阅knife4j文档
评论区