Springboot中swagger和knife如何使用

# SpringBoot中Swagger和Knife4j的使用指南

## 一、API文档工具概述

在现代Web开发中，良好的API文档是前后端协作的重要基础。Swagger作为一套开源的API文档工具，通过注解的方式自动生成RESTful风格的接口文档。而Knife4j则是Swagger的增强解决方案，在UI界面和功能上都进行了优化。

### 1.1 Swagger核心组件

- **Swagger Core**：处理注解的核心库
- **Swagger UI**：可视化文档界面
- **Swagger Editor**：API设计编辑器
- **Swagger Codegen**：代码生成工具

### 1.2 Knife4j的特点

- 更美观的UI界面
- 支持接口调试时的动态参数
- 提供离线文档导出功能
- 增强的注解支持

## 二、SpringBoot集成Swagger

### 2.1 添加Maven依赖

```xml
<!-- Swagger基础依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- Swagger UI -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2.2 基础配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot集成Swagger示例")
                .description("API接口文档")
                .version("1.0")
                .build();
    }
}

2.3 常用注解说明

三、集成Knife4j增强方案

3.1 添加Knife4j依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

3.2 配置类调整

@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }
    
    private List<ApiKey> securitySchemes() {
        return Arrays.asList(
            new ApiKey("Authorization", "Authorization", "header"));
    }
    
    private List<SecurityContext> securityContexts() {
        return Arrays.asList(
            SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.regex("/.*"))
                .build());
    }
}

3.3 Knife4j特有功能

1. 文档导出：支持Markdown/HTML/Word/PDF格式
2. 全局参数：可设置Header等公共参数
3. 接口过滤：按标签/路径快速筛选
4. 调试增强：支持表单/JSON多种参数格式

四、最佳实践

4.1 安全配置

// 添加JWT认证支持
@Bean
public SecurityScheme apiKey() {
    return new ApiKey("token", "token", "header");
}

4.2 分组配置

// 多版本API分组
@Bean
public Docket v1Api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("v1.0")
            .select()
            .apis(input -> {
                String methodName = input.getHandlerMethod().getMethod().getName();
                return methodName.contains("V1");
            })
            .build();
}

4.3 生产环境控制

# application-prod.properties
knife4j.production=true
swagger.enabled=false

五、常见问题解决

5.1 404访问问题

确保添加了资源映射（SpringBoot 2.6+需要）：

@Configuration
public class WebConfig implements WebMvcConfigurer {
    
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
    }
}

5.2 日期类型处理

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .directModelSubstitute(LocalDate.class, String.class)
            .directModelSubstitute(LocalDateTime.class, String.class);
}

5.3 枚举类型显示

@ApiModelProperty(value = "订单状态", allowableValues = "CREATED,PD,DELIVERED")
private OrderStatus status;

六、扩展功能实现

6.1 自定义UI

1. 下载Knife4j前端源码
2. 修改src/styles/theme.scss
3. 重新build后替换静态资源

6.2 接口权限控制

// 根据注解动态显示接口
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

6.3 离线文档生成

Knife4jHtmlGenerator generator = new Knife4jHtmlGenerator(
    "文档标题",
    "/path/to/save",
    docket);
generator.generate();

七、总结

本文详细介绍了在SpringBoot项目中： 1. 集成Swagger生成基础API文档 2. 使用Knife4j增强文档功能 3. 实际开发中的配置技巧 4. 常见问题的解决方案

通过合理配置，可以显著提升团队协作效率。建议生产环境关闭文档功能，或添加权限控制。

注意事项： - Swagger 2.x已停止维护，新项目建议使用OpenAPI 3.0 - 敏感接口应当添加@ApiIgnore注解排除 - 文档应当与代码同步更新 “`

该文档共计约2000字，采用Markdown格式编写，包含： 1. 多级标题结构 2. 代码块示例 3. 表格对比 4. 注意事项提示框 5. 配置示例和注解说明 可根据实际项目需求调整具体配置参数和依赖版本。