# 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> @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(); } } | 注解 | 作用 | 示例 |
|---|---|---|
| @Api | 修饰Controller类 | @Api(tags = “用户管理”) |
| @ApiOperation | 修饰方法 | @ApiOperation(“创建用户”) |
| @ApiParam | 修饰参数 | @ApiParam(“用户ID”) Long id |
| @ApiModel | 修饰实体类 | @ApiModel(“用户实体”) |
| @ApiModelProperty | 修饰字段 | @ApiModelProperty(“用户名”) |
<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>3.0.3</version> </dependency> @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()); } } // 添加JWT认证支持 @Bean public SecurityScheme apiKey() { return new ApiKey("token", "token", "header"); } // 多版本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(); } # application-prod.properties knife4j.production=true swagger.enabled=false 确保添加了资源映射（SpringBoot 2.6+需要）：
@Configuration public class WebConfig implements WebMvcConfigurer { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("doc.html") .addResourceLocations("classpath:/META-INF/resources/"); } } @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .directModelSubstitute(LocalDate.class, String.class) .directModelSubstitute(LocalDateTime.class, String.class); } @ApiModelProperty(value = "订单状态", allowableValues = "CREATED,PD,DELIVERED") private OrderStatus status; src/styles/theme.scss// 根据注解动态显示接口 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) 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. 配置示例和注解说明 可根据实际项目需求调整具体配置参数和依赖版本。
免责声明：本站发布的内容（图片、视频和文字）以原创、转载和分享为主，文章观点不代表本网站立场，如果涉及侵权请联系站长邮箱：is@yisu.com进行举报，并提供相关证据，一经查实，将立刻删除涉嫌侵权内容。
