Java、SpringBoot中配置接口文档，knife4j、swagger
Java、SpringBoot中配置接口文档，knife4j、swagger
knife配置
官网：https://doc.xiaominfo.com/
我这里以最新版的为例，SpringBoot版本是3.0.0以上的
需要注意的是自动集成了swagger，每个SpringBoot版本会对应其knfie版本，swagger也一样，如果配置了不同的版本一定要看官网介绍，否则启动时就会报错，亲身经历。
我这里SpringBoot是 3.0.0往上的！！！
如果需要配置，生产环境不开放接口下面也有介绍，也可以设置接口访问密码用户名等。
需要在pom.xml中导入以下
使用idea创建完项目直接将下面放进去之后刷新下就可以了，不需要再引入其它东西了，而且也集成了swagger
<dependency>
<groupId>com.github.xiaoymingroupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starterartifactId>
<version>4.3.0version>
dependency>
因为这个是SpringBoot 3.0.0以上的所以不需要导入
swagger为了看的清楚我将我
pom.xml所有的内容都放进来，如果出错也有个参考<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0modelVersion> <parent> <groupId>org.springframework.bootgroupId> <artifactId>spring-boot-starter-parentartifactId> <version>3.2.1version> <relativePath/> parent> <groupId>com.examplegroupId> <artifactId>knife4jartifactId> <version>0.0.1-SNAPSHOTversion> <name>knife4jname> <description>knife4jdescription> <properties> <java.version>17java.version> properties> <dependencies> <dependency> <groupId>org.springframework.bootgroupId> <artifactId>spring-boot-starter-webartifactId> dependency> <dependency> <groupId>org.projectlombokgroupId> <artifactId>lombokartifactId> <optional>trueoptional> dependency> <dependency> <groupId>org.springframework.bootgroupId> <artifactId>spring-boot-starter-testartifactId> <scope>testscope> dependency> <dependency> <groupId>com.github.xiaoymingroupId> <artifactId>knife4j-openapi3-jakarta-spring-boot-starterartifactId> <version>4.3.0version> dependency> dependencies> <build> <plugins> <plugin> <groupId>org.springframework.bootgroupId> <artifactId>spring-boot-maven-pluginartifactId> <configuration> <excludes> <exclude> <groupId>org.projectlombokgroupId> <artifactId>lombokartifactId> exclude> excludes> configuration> plugin> plugins> build> project>
配置文件中
# springdoc-openapi项目配置
springdoc:
swagger-ui:
path: /swagger-ui.html
tags-sorter: alpha
operations-sorter: alpha
api-docs:
path: /v3/api-docs
# 分组也可以在 Knife4jConfig 文件目录下胚子
group-configs:
- group: 'All API'
paths-to-match: '/**'
packages-to-scan: com.example.knife4j
# knife4j的增强配置，不需要增强可以不配
knife4j:
enable: true
production: true # 开启生产环境屏蔽，开发测试要设为true否则看不到
setting:
language: zh_cn
basic:
enable: true
username: test # Basic认证用户名
password: 123 # Basic认证密码
目录结构
为了演示清楚些，我将目录结构附上
配置文件Knife4jConfig
如果在yml配置文件中设置了分组这里也设置了相同的分组会以Knife4jConfig为准，会覆盖掉yml中的。
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class Knife4jConfig {
// 创建 admin API分组
@Bean
public GroupedOpenApi sessionApi() {
return GroupedOpenApi.builder()
.group("session接口")
.pathsToMatch("/session/**")
.build();
}
// 创建 token API分组
@Bean
public GroupedOpenApi tokenApi() {
return GroupedOpenApi.builder()
.group("token接口")
.pathsToMatch("/token/**")
.build();
}
// 创建 jwt API分组
@Bean
public GroupedOpenApi JWTApi() {
return GroupedOpenApi.builder()
.group("jwt接口")
.pathsToMatch("/jwt/**")
.build();
}
// 配置名称等信息
@Bean
public OpenAPI customerOpenApi() {
return new OpenAPI().info(
new Info()
.title("接口文档")
.version("1.0")
.contact(new Contact()
.name("bunny")));
}
}
写个简单接口测试下DemoController
- 访问路径为：
- knife：http://localhost:8080/doc.html
- swagger：http://localhost:8080/swagger-ui/index.html
注意你自己的路径和端口号。
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@Tag(name = "测试接口")
public class DemoController {
@RequestMapping("hello")
@Operation(summary = "hello接口", description = "Hello消息描述")
public String hello() {
return "Hello";
}
}
在丝袜哥中也可以
Swagger 配置
其实SpringBoot版本高点，直接引入knife也可以看到swagger。
如果想单独设置swagger也可以。
pom.xml中导入
<dependency>
<groupId>io.swagger.core.v3groupId>
<artifactId>swagger-annotationsartifactId>
<version>2.2.15version>
dependency>
<dependency>
<groupId>org.springdocgroupId>
<artifactId>springdoc-openapi-starter-webmvc-uiartifactId>
<version>2.1.0version>
dependency>
和上面一样我将里面内容都导入进来好有个对比
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0modelVersion> <parent> <groupId>org.springframework.bootgroupId> <artifactId>spring-boot-starter-parentartifactId> <version>3.2.1version> <relativePath/> parent> <groupId>com.examplegroupId> <artifactId>swaggerartifactId> <version>0.0.1-SNAPSHOTversion> <name>swaggername> <description>swaggerdescription> <properties> <java.version>17java.version> properties> <dependencies> <dependency> <groupId>org.springframework.bootgroupId> <artifactId>spring-boot-starter-webartifactId> dependency> <dependency> <groupId>org.projectlombokgroupId> <artifactId>lombokartifactId> <optional>trueoptional> dependency> <dependency> <groupId>org.springframework.bootgroupId> <artifactId>spring-boot-starter-testartifactId> <scope>testscope> dependency> <dependency> <groupId>io.swagger.core.v3groupId> <artifactId>swagger-annotationsartifactId> <version>2.2.15version> dependency> <dependency> <groupId>org.springdocgroupId> <artifactId>springdoc-openapi-starter-webmvc-uiartifactId> <version>2.1.0version> dependency> dependencies> <build> <plugins> <plugin> <groupId>org.springframework.bootgroupId> <artifactId>spring-boot-maven-pluginartifactId> <configuration> <excludes> <exclude> <groupId>org.projectlombokgroupId> <artifactId>lombokartifactId> exclude> excludes> configuration> plugin> plugins> build> project>
编写一个简单的接口
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@Tag(name = "测试接口")
public class DemoController {
@RequestMapping("hello")
@Operation(summary = "hello接口", description = "Hello消息描述")
public String hello() {
return "Hello";
}
}
