网站服务器代码放在哪,建立自己的影视网站,免费的微商城开发,如何用dw做网站在现代 Web 应用开发中#xff0c;API 文档的重要性不言而喻。清晰、准确、易用的 API 文档不仅可以方便开发者理解和使用 API#xff0c;还能提高团队协作效率。Knife4j 是一个基于 Swagger 的增强型 API 文档工具#xff0c;它可以为 Spring Boot 项目生成美观、易于交互的… 在现代 Web 应用开发中API 文档的重要性不言而喻。清晰、准确、易用的 API 文档不仅可以方便开发者理解和使用 API还能提高团队协作效率。Knife4j 是一个基于 Swagger 的增强型 API 文档工具它可以为 Spring Boot 项目生成美观、易于交互的 API 文档本文将介绍如何在 Spring Boot 项目中整合 Knife4j并提供详细的代码示例和最佳实践。
一、为什么选择 Knife4j Knife4j 是一个基于 Swagger 的增强型 API 文档框架相比于 Swagger UIKnife4j 提供了更强大的功能和更好的用户体验
界面美观 Knife4j 提供了更加美观和现代的界面使得 API 文档更具吸引力。功能强大 Knife4j支持在线调试、参数示例、离线文档导出等多种实用功能。易于集成 Knife4j 可以轻松地与 Spring Boot 集成。支持多种主题 Knife4j 提供了多种主题可以自定义 API 文档的风格。更好的可读性 Knife4j 在 API文档的呈现上做了优化使其更易于阅读和理解。
二、Spring Boot 整合 Knife4j实践
2.1 添加 Knife4j 依赖
dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-spring-boot-starter/artifactIdversion3.0.3/version
/dependencydependencyartifactIdguava/artifactIdgroupIdcom.google.guava/groupIdversion29.0-jre/version
/dependency注意 请使用合适的版本号确保你的 Spring Boot 版本与 Knife4j 和 Swagger 兼容。
2.2 创建 Swagger 配置类
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import com.google.common.base.Function;
import com.google.common.base.Optional;
import com.google.common.base.Predicate;
import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.RequestHandler;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;Configuration
EnableSwagger2
EnableKnife4j
ConditionalOnWebApplication
public class SwaggerConfig implements WebMvcConfigurer {/*** 定义分隔符*/private static final String SPLITOR ;;Bean(value systemApi)public Docket createSystemRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName(1.系统管理模块).select().apis(basePackage(com.extend.chk.system.controller)).paths(PathSelectors.any()).build();}Bean(value reportApi)public Docket createReportRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName(2.数据可视化模块).select().apis(basePackage(com.extend.chk.report.controller)).paths(PathSelectors.any()).build();}Bean(value warnApi)public Docket createWarnRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName(3.预警模块).select().apis(basePackage((com.extend.chk.warn.controller))).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().description(学习管理平台接口文档).version(v1.0.0).title(学习管理平台接口文档).build();}/*** 重写basePackage方法使能够实现多包访问* param basePackage* return*/public static PredicateRequestHandler basePackage(final String basePackage) {return input - declaringClass(input).transform(handlerPackage(basePackage)).or(true);}private static FunctionClass?, Boolean handlerPackage(final String basePackage) {return input - {// 循环判断匹配for (String strPackage : basePackage.split(SPLITOR)) {boolean isMatch input.getPackage().getName().startsWith(strPackage);if (isMatch) {return true;}}return false;};}private static Optional? extends Class? declaringClass(RequestHandler input) {return Optional.fromNullable(input.declaringClass());}/*** 配置静态资源* param registry*/Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler(/static/**).addResourceLocations(classpath:/static/);}
}Configuration: 标识这是一个配置类用来定义 Bean 或其他配置信息。EnableSwagger2: 启用 Swagger 2 来生成和管理 RESTful API 的文档。EnableKnife4j增强 Swagger UI 的展示效果提供更美观、功能更丰富的 API 文档界面。ConditionalOnWebApplication确保上述配置仅在应用程序为 Web 应用时才生效。Bean: 创建 Docket Bean用于配置 Swagger 文档信息。apiInfo(): 配置 API的基本信息例如标题、描述、版本号等。apis(basePackage((com.extend.chk.warn.controller))): 指定生成API 文档的 Controller 所在的包。paths(PathSelectors.any()): 定义路径过滤规则决定哪些 URL 路径应被包含在文档中这里设置为所有路径。groupName(1.系统管理模块)为生成的 API 分组指定名称。这可以将不同的 API 接口按功能或模块进行分类展示。
2.3 在类上使用 Swagger 注解
2.3.1 在controller里面使用Swagger 注解
Api(tags 项目管理)
RestController
RequestMapping(/project/manage)
public class ProjectManageController extends BaseController {Autowiredprivate ProjectManageService ProjectManageService;ApiOperation(value 查询项目列表)GetMapping(/list)public ResultPageDataInfoProjectManage queryProjectManageList(ProjectManageReq req) {return success(buildPageDataInfo(ProjectManageService.queryProjectManageList(req)));}ApiOperation(value 查询项目详情)GetMapping(/query)public ResultProjectManage queryProjectManageById(Integer workspaceId, Integer projectId) {return success(ProjectManageService.queryProjectManageById(workspaceId, projectId));}ApiOperation(value 项目新增)PostMapping(value /add)Log(title 项目新增, businessType BusinessType.INSERT)public Result addProjectManage(Validated RequestBody ProjectManage ProjectManage) {ProjectManageService.addProjectManage(ProjectManage);return success();}ApiOperation(value 项目修改)PostMapping(value /update)Log(title 项目修改, businessType BusinessType.UPDATE)public Result updateProjectManage(Validated RequestBody ProjectManage ProjectManage) {ProjectManageService.updateProjectManage(ProjectManage);return success();}ApiOperation(value 项目删除)ApiImplicitParams({ApiImplicitParam(name workspaceId, value 空间id, required true),ApiImplicitParam(name projectId, value 项目id, required true)})PutMapping(value /delete)Log(title 项目删除, businessType BusinessType.DELETE)public Result operateProjectManage(Integer workspaceId, Integer projectId) {ProjectManageService.operateProjectManage(workspaceId, projectId);return success();}
}Api: 用于描述 Controller 的基本信息例如分类标签。ApiOperation: 用于描述 API的基本信息例如接口名称、描述等。ApiImplicitParam: 用于描述 API的参数信息例如参数名称、类型、是否必填等。
2.3.2 在请求类和返回类里面使用Swagger 注解
ApiModel(value ProjectManage对象, description 项目管理表)
public class ProjectManage extends BaseEntityProjectManage {private static final long serialVersionUID 1L;ApiModelProperty(主键id)private Integer id;ApiModelProperty(项目名称)private String name;ApiModelProperty(项目负责人id)private String ownerId;ApiModelProperty(项目成员id)private String memberId;ApiModelProperty(工作空间id)private Integer workspaceId;ApiModelProperty(项目状态(1-有效 2-失效))private String status;Overridepublic Serializable pkVal() {return this.id;}
}ApiModel用于描述一个模型类通常是一个 DTO 或实体类提供该模型的详细信息如名称、描述等。它使得生成的 API文档能够清晰地展示数据模型的用途和结构。ApiModelProperty用于描述模型类中的具体字段指定字段的名称、类型、是否必填、默认值、备注等信息。这有助于开发者更好地理解每个字段的意义和用法。
2.4 访问 Knife4j 文档
启动 Spring Boot 应用并在浏览器中访问以下地址即可查看 Knife4j 生成的 API 文档
http://localhost:8080/extend/doc.html#/home三、最佳实践
使用 Swagger 注解描述 API 使用 Swagger 注解详细描述 API 的参数、响应、错误码等提高文档的可读性。根据API 分组 使用 Swagger 的分组功能将 API 分类展示方便用户查找。添加 API 示例 在 Swagger注解中添加 API 示例帮助用户快速了解 API 的使用方法。保持 API 文档与代码同步 确保 API文档和代码同步更新避免出现文档与代码不一致的问题。使用清晰的 API 命名 使用清晰的 API 命名和参数命名提高 API的可读性。
