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.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.3.0</version>
</dependency>

因为这个是SpringBoot 3.0.0以上的所以不需要导入swagger

为了看的清楚我将我pom.xml所有的内容都放进来，如果出错也有个参考

<?xml version="1.0" encoding="UTF-8"?>
<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.0</modelVersion><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>3.2.1</version><relativePath/> <!-- lookup parent from repository --></parent><groupId>com.example</groupId><artifactId>knife4j</artifactId><version>0.0.1-SNAPSHOT</version><name>knife4j</name><description>knife4j</description><properties><java.version>17</java.version></properties><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency><!-- knife4j --><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.3.0</version></dependency></dependencies><build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><configuration><excludes><exclude><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId></exclude></excludes></configuration></plugin></plugins></build>
</project>

配置文件中

# springdoc-openapi项目配置
springdoc:swagger-ui:path: /swagger-ui.htmltags-sorter: alphaoperations-sorter: alphaapi-docs:path: /v3/api-docs
#    分组也可以在 Knife4jConfig 文件目录下胚子group-configs:- group: 'All API'paths-to-match: '/**'packages-to-scan: com.example.knife4j# knife4j的增强配置，不需要增强可以不配
knife4j:enable: trueproduction: true  # 开启生产环境屏蔽，开发测试要设为true否则看不到setting:language: zh_cnbasic:enable: trueusername: 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分组@Beanpublic GroupedOpenApi sessionApi() {return GroupedOpenApi.builder().group("session接口").pathsToMatch("/session/**").build();}// 创建 token API分组@Beanpublic GroupedOpenApi tokenApi() {return GroupedOpenApi.builder().group("token接口").pathsToMatch("/token/**").build();}// 创建 jwt API分组@Beanpublic GroupedOpenApi JWTApi() {return GroupedOpenApi.builder().group("jwt接口").pathsToMatch("/jwt/**").build();}// 配置名称等信息@Beanpublic 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`中导入

<!-- swagger2 -->
<dependency><groupId>io.swagger.core.v3</groupId><artifactId>swagger-annotations</artifactId><version>2.2.15</version>
</dependency>
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.1.0</version>
</dependency>

和上面一样我将里面内容都导入进来好有个对比

<?xml version="1.0" encoding="UTF-8"?>
<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.0</modelVersion><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>3.2.1</version><relativePath/> <!-- lookup parent from repository --></parent><groupId>com.example</groupId><artifactId>swagger</artifactId><version>0.0.1-SNAPSHOT</version><name>swagger</name><description>swagger</description><properties><java.version>17</java.version></properties><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency><!-- swagger2 --><dependency><groupId>io.swagger.core.v3</groupId><artifactId>swagger-annotations</artifactId><version>2.2.15</version></dependency><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.1.0</version></dependency></dependencies><build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><configuration><excludes><exclude><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId></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";}
}