springboot 整swagger knife4j

开发人员强调了API文档的重要性，特别是在系统集成过程中。最近注意到了swagger和knife4j，它们提供了方便的API文档生成和调试功能。因此，今天想分享一期关于springboot整合swagger和knife4j的经验。希望大家喜欢！

Spring Boot 框架集成Knife4j | Knife4j (xiaominfo.com)

1. 简述Swagger和Knife4j

Swagger是一个开源的、用于编写API文档的框架。它可以帮助我们通过Swagger UI对API文档进行在线展示，从而实现API文档的可视化管理。

然而，Swagger在UI界面上的表现并不是很出色。因此，为了增强Swagger的UI交互体验，我们可以使用Knife4j对其进行美化和强化。

Knife4j是Swagger-UI的增强版，它是在Swagger-UI的基础上进行了改进和优化，提供了更加完善的交互体验和更加美观的UI设计。同时，它也提供了更多的扩展功能，例如在线调试和多语言支持等

2.版本分析

1. Knife4j底层依赖springfox，因此无需再单独引入Springfox的具体版本，且两者有对应的版本要求，否则会产生很多冲突；
2. 使用Knife4j2.0.6及以上的版本，Spring Boot的版本必须大于等于2.2.x；

1.添加依赖

<?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>
        <artifactId>spring-boot-starter-parent</artifactId>
        <groupId>org.springframework.boot</groupId>
        <version>2.7.3</version>
    </parent>
    <groupId>org.ljy.tem</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.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.2</version>
        </dependency>




    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

2.配置config类

3.添加contrlloer  添加注解 

1. `@Api`：标记接口类或接口方法，用于生成接口文档。
   - `value`：接口描述
   - `tags`：接口分组
   - `hidden`：是否隐藏接口文档，默认为 false

```java
@Api(value = "UserController", tags = "用户管理接口")
@RestController
@RequestMapping("/user")
public class UserController {
    // 接口方法
}
```

2. `@ApiOperation`：标记接口方法，用于生成接口文档。
   - `value`：接口方法描述
   - `notes`：接口方法详细说明

```java
@ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息")
@GetMapping("/{id}")
public User getUserById(@PathVariable Long id) {
    // 方法实现
}
```

3. `@ApiParam`：标记接口方法参数，用于生成参数文档。
   - `value`：参数描述
   - `name`：参数名称
   - `required`：是否必填，默认为 true
   - `defaultValue`：参数默认值

```java
@ApiOperation(value = "更新用户信息", notes = "根据用户ID更新用户信息")
@PutMapping("/{id}")
public void updateUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long id,
                           @ApiParam(value = "用户名") @RequestParam String username) {
    // 方法实现
}

4. 启动访问 localhost:8888/doc.html

 当访问时doc.html 404

   需要继承

WebMvcConfigurationSupport

/**
 * 设置静态资源映射
 * @param registry
 */
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}

 参考:SpringBoot访问doc.html页面404 | Knife4j (xiaominfo.com)