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.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中导入

<!-- 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";
    }
}