Spring Boot 2整合Knife4j自动生成API文档

Spring Boot 2整合Knife4j自动生成API文档教程

上一期介绍了springboot3进行使用Knife4j的教程,但是在实际的开发中,还是有很多的项目使用的是springboot2使用Knife4j,所以这期进行介绍springboot2如何的进行整合Knife4j.

介绍

在微服务架构和前后端分离的开发模式中，API文档的管理和维护变得尤为重要。Swagger是一个广泛使用的框架，用于生成、描述、调用和可视化RESTful Web服务。Knife4j作为Swagger的增强UI，提供了更优雅的界面和更丰富的功能。本教程将指导您如何在Spring Boot 2项目中整合Knife4j以自动生成API文档。

一、准备工作

确保您已经有一个Spring Boot 2项目。如果没有，可以通过Spring Initializr快速生成一个。

二、添加Knife4j依赖

1. 打开项目的pom.xml文件。

2. 添加Knife4j的依赖。根据搜索结果，您可能需要添加如下依赖：

<dependency>    
<groupId>com.github.xiaoymingroupId> 
   <artifactId>knife4j-spring-boot-starterartifactId>   
 <version>3.0.2version> 
</dependency>

三、配置Swagger

创建一个Swagger配置类，通常命名为SwaggerConfig。

@Configuration
@Slf4j
public class SwaggerConfig {
    @Bean    public Docket docket() {
        // 配置接口文档的基本信息
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("fus接口")
                .version("2.0")
                .description("fus个人接口")
                .build();        // 创建一个新的Docket实例，并指定使用Swagger 2标准来生成文档。
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo) // 指定api文档的基本信息
                .select() // 调用select方法开始配置哪些API会被Swagger文档化。                // 指定要生成Api文档的包          
                .apis(RequestHandlerSelectors.basePackage("com.sky.controller"))              
        // 选择所有路径进行文档化。PathSelectors.any()同样表示没有过滤条件，所有的HTTP路径都会被包含。               
            .paths(PathSelectors.any()) // 所有的请求路径               
                .build();        return docket;   }          
    /**     * 设置静态资源映射     * @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/");  
    }
}

注意:

• apis: apis是用来选择哪些控制器（Controller）类会被包含在自动生成的Swagger文档中.

• paths : paths是指HTTP请求的路径，它用来选择哪些具体的HTTP路径（URL模式）会被包含在Swagger文档中。

四、使用Swagger注解

在您的控制器和模型类中使用Swagger注解，例如：

实体类

@Data
@ApiModel(description = "用户登录时传递的数据模型")
// api实体类说明 
public class UserLoginDTO implements Serializable {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;
}

实体类的进行展示的 Swagger models中。

Controller类

import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation;
@RestController
@Api(tags = "用户管理") 
public class UserController {   
    @GetMapping("/users")    
    @ApiOperation(value = "获取用户列表", notes = "这里可以写获取用户列表的详细描述") 
    public List<User> listUsers() {    
    // ...  
     }
}

五、启动项目并访问文档

启动您的Spring Boot项目，然后在浏览器中访问Knife4j提供的API文档界面：

http://localhost:8080/swagger-ui.html

或者访问Knife4j的增强UI：

http://localhost:8080/doc.html

六、Knife4j的特点

• 美观界面：Knife4j提供了比Swagger UI更美观的界面。

• 功能丰富：除了基本的文档浏览和接口测试功能，Knife4j还支持文档管理，可以导出多种格式的API文档。

七、注意事项

• Spring Boot版本：如果您的Spring Boot版本高于等于2.6，可能需要配置路径匹配策略，以避免启动错误。

• 生产环境：在生产环境中，您可能需要配置Knife4j以屏蔽文档接口，以防止敏感信息泄露。

• spring boot3 和使用springboot2使用的方式不同.

八、结语

通过上述步骤，您应该能够在Spring Boot 2项目中成功整合Knife4j，并自动生成API文档。Knife4j作为一个强大的文档管理工具，可以大大提高团队的协作效率和接口管理的便捷性。