目录一、SpringDoc1.添加依赖2.配置代码配置解释1springdoc.api-docs.path2springdoc.swagger-ui.path3springdoc.swagger-ui.operationsSorter4springdoc.swagger-ui.tagsSorter5springdoc.title使用3.控制器处理4.访问5.优点6.缺点二、swagger1. 添加依赖项2. 配置 Swagger3. 将注释添加到控制器中4. 访问 Swagger UI5.优点6.缺点Swagger和Springdoc是两个常用的工具用于生成和维护API文档特别是针对基于REST的Web服务。它们有效地提升了API的可读性和可维护性帮助开发者、产品经理和其他利益相关者更好地理解和使用所提供的API。注意Swagger支持springboot2.0但不支持springboot3.0一、SpringDocSpringdoc是一个开源的库旨在将Spring Boot项目的RESTful API与OpenAPI 3文档生成器集成。Springdoc与Spring Boot应用无缝集成并支持包括Swagger UI在内的多种用户界面。1.添加依赖dependencies dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId version2.6.0/version /dependency /dependencies2.配置代码添加一个配置类并添加xml配置配置解释springdoc: api-docs: path: /v3/api-docs swagger-ui: path: /swagger-ui.html operationsSorter: method tagsSorter: alpha1springdoc.api-docs.path属性路径:springdoc.api-docs.path作用: 定义 OpenAPI 文档的访问路径。默认值:/v3/api-docs示例:springdoc: api-docs: path: /v3/api-docs配置后API 文档可以通过http://host:port/v3/api-docs访问。2springdoc.swagger-ui.path属性路径:springdoc.swagger-ui.path作用: 定义 Swagger UI 的访问路径。默认值:/swagger-ui.html示例:springdoc: swagger-ui: path: /swagger-ui.html配置后Swagger UI 可以通过http://host:port/swagger-ui.html访问。3springdoc.swagger-ui.operationsSorter属性路径:springdoc.swagger-ui.operationsSorter作用: 定义如何对 Swagger UI 中的操作进行排序。可选值:alpha: 按照操作名称的字母顺序排列。method: 按照 HTTP 方法进行排序如 GET, POST, PUT, DELETE。示例:springdoc: swagger-ui: operationsSorter: method配置后操作会按照 HTTP 方法的顺序显示。4springdoc.swagger-ui.tagsSorter属性路径:springdoc.swagger-ui.tagsSorter作用: 定义如何对 Swagger UI 中的标签进行排序。可选值:alpha: 按照标签名称的字母顺序排列。示例:springdoc: swagger-ui: tagsSorter: alpha配置后标签会按照字母顺序显示。5springdoc.title属性路径:springdoc.title作用: 设置整个 API 文档的标题。示例:springdoc: title: 用户管理配置后生成的 API 文档的标题会显示为“用户管理”。使用package com.ck.framework.common.springdoc.config; import io.swagger.v3.oas.models.OpenAPI; import io.swagger.v3.oas.models.info.Contact; import io.swagger.v3.oas.models.info.Info; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; /** * ClassName SpringDocConfig * Description * Author * Date 2024/8/28 15:55 * Version 1.0 */ Configuration public class SpringDocConfig { Autowired private BaseConfig baseConfig; Bean public OpenAPI createOpenApi() { return new OpenAPI() .info(createInfo()); } private Info createInfo() { return new Info() .contact(createContact()) .title(baseConfig.getTitle()) .description(baseConfig.getDescription()) .version(baseConfig.getVersion()); } private Contact createContact() { Contact contact new Contact(); contact.name(baseConfig.getContactName()); contact.url(baseConfig.getContactUrl()); contact.email(baseConfig.getContactEmail()); return contact; } }3.控制器处理需要再Controller里面加上Tag注解package com.ck.framework.user.controller; import com.ck.framework.common.web.bean.Result; import com.ck.framework.user.entity.PageResult; import com.ck.framework.user.entity.dto.UserDto; import com.ck.framework.user.entity.po.UserPo; import com.ck.framework.user.entity.req.UserListReq; import com.ck.framework.user.entity.req.UserReq; import com.ck.framework.user.service.UserService; import io.swagger.v3.oas.annotations.tags.Tag; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.*; /** * ClassName UserController * Description * Author * Date 2024/8/24 0:03 * Version 1.0 */ RestController RequestMapping(/user) Tag(name 用户管理) public class UserController { Autowired private UserService userService; PostMapping public ResultBoolean addUser(RequestBody UserReq userReq) { UserDto userDto new UserDto(); userDto.setName(userReq.getName()); userDto.setAge(userReq.getAge()); int num userService.addUser(userDto); if (num 0) { return Result.success(true); } else { return Result.fail(); } } DeleteMapping(/{id}) public ResultBoolean deleteUser(RequestBody UserReq userReq) { UserDto userDto new UserDto(); userDto.setId(userReq.getId()); int num userService.delUser(userDto); if (num 0) { return Result.success(true); } else { return Result.fail(); } } GetMapping public ResultPageResultUserPo getUserPage(RequestBody UserListReq userListReq) { UserDto userDto new UserDto(); userDto.setPageIndex(userListReq.getPageIndex()); userDto.setPageSize(userListReq.getPageSize()); PageResultUserPo pageResult userService.getUserPage(userDto); return Result.success(pageResult); } }4.访问5.优点无缝集成:专为 Spring Boot 设计非常容易集成到 Spring Boot 应用中。减少注解:可以自动解析 Spring MVC 或 Spring WebFlux 控制器减少了需要添加的注解数量。自动化配置:大量依赖默认配置无需复杂的手动配置开箱即用。支持最新技术:支持 Spring Boot 2.x 及更高版本跟进 Spring 生态系统的最新发展。丰富的文档和示例:提供了良好的文档和示例帮助开发者快速上手。6.缺点局限性:专门面向 Spring Boot 项目不适用于其他框架或原生 Spring 项目。功能相对简单:相对于 Swagger 提供的完整工具链Springdoc 的功能相对单一主要聚焦于文档生成。二、swaggerSwagger是一个用于生成、描述、调用和可视化 RESTful Web 服务的开源框架。它的核心是一个名为 OpenAPI 规范的描述性语言。Swagger 是 Java 应用程序中常用的工具之一因为它能自动生成 API 文档并提供一个用户友好的接口来测试 API。在 Java 项目中使用 Swagger 通常包括以下步骤1. 添加依赖项首先你需要在你的项目中添加所需的 Swagger 依赖项。以 Maven 项目为例在pom.xml文件中添加以下依赖dependencies dependency groupIdio.springfox/groupId artifactIdspringfox-swagger-ui/artifactId version3.0.0/version /dependency dependency groupIdio.springfox/groupId artifactIdspringfox-swagger2/artifactId version3.0.0/version /dependency /dependencies2. 配置 Swagger添加一个 Swagger 配置类。例如在 Spring Boot 应用程序中你可以添加以下内容package com.ck.framework.common.swagger.config; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * ClassName SwaggerConfig * Description 配置Swagger的类启用Swagger并定义API文档的相关信息 * Author * Date 2024/8/28 08:31 * Version 1.0 */ Configuration // 表示这是一个配置类 EnableSwagger2 // 启用Swagger2 public class SwaggerConfig { /** * 创建一个Docket Bean用于配置Swagger的核心内容包括哪些包中的API需要生成文档和API的基本信息。 * * return Docket对象用于Swagger的配置 */ public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) // 指定文档类型为Swagger2 .apiInfo(apiInfo()) // 配置API信息 .select() // 返回一个ApiSelectorBuilder实例用于控制哪些接口暴露给swagger .apis(RequestHandlerSelectors.basePackage(com.ck.framework.common.swagger)) // 选择扫描的包名 .paths(PathSelectors.ant(/*)) // 选择哪些路径的API需要生成文档 .build(); // 构建Docket实例 } /** * 构建API基本信息用于页面展示的文档信息。 * * return ApiInfo对象包含相关API的描述信息 */ public ApiInfo apiInfo() { return new ApiInfoBuilder() .title() // 设置文档标题 .description( 测试swagger) // 设置文档描述信息 .contact(new Contact(, git地址, zhuchb_0509163.com)) // 设置联系人信息 .version(1.0) // 设置文档版本 .build(); // 构建ApiInfo实例 } }3. 将注释添加到控制器中使用 Swagger 注释描述注册到Controller。例如package com.ck.framework.user.controller; import com.ck.framework.common.web.bean.Result; import com.ck.framework.user.entity.PageResult; import com.ck.framework.user.entity.dto.UserDto; import com.ck.framework.user.entity.po.UserPo; import com.ck.framework.user.entity.req.UserListReq; import com.ck.framework.user.entity.req.UserReq; import com.ck.framework.user.service.UserService; import io.swagger.annotations.Api; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.*; /** * ClassName UserController * Description * Author * Date 2024/8/24 0:03 * Version 1.0 */ RestController RequestMapping(/user) Api(value 用户管理) public class UserController { Autowired private UserService userService; PostMapping public ResultBoolean addUser(RequestBody UserReq userReq) { UserDto userDto new UserDto(); userDto.setName(userReq.getName()); userDto.setAge(userReq.getAge()); int num userService.addUser(userDto); if (num 0) { return Result.success(true); } else { return Result.fail(); } } DeleteMapping(/{id}) public ResultBoolean deleteUser(RequestBody UserReq userReq) { UserDto userDto new UserDto(); userDto.setId(userReq.getId()); int num userService.delUser(userDto); if (num 0) { return Result.success(true); } else { return Result.fail(); } } GetMapping public ResultPageResultUserPo getUserPage(RequestBody UserListReq userListReq) { UserDto userDto new UserDto(); userDto.setPageIndex(userListReq.getPageIndex()); userDto.setPageSize(userListReq.getPageSize()); PageResultUserPo pageResult userService.getUserPage(userDto); return Result.success(pageResult); } }4. 访问 Swagger UI启动你的 Spring Boot 应用程序后打开浏览器访问http://localhost:8080/swagger-ui.html你会看到自动生成的 API 文档及其用户界面。5.优点工具链完备:Swagger 提供了全面的工具包括 Swagger Editor、Swagger Codegen 和 Swagger UI这些工具可以涵盖从开发到文档化的各个环节。广泛支持:被多个语言和框架广泛支持几乎成为业界标准。丰富的插件和社区支持:有大量的插件和扩展可以满足各种自定义需求。可视化交互:Swagger UI 提供了极为友好的界面允许开发者甚至非技术人员进行直接的API测试与调用。6.缺点集成复杂:对于部分框架或语言需要较多的配置和集成工作。注解依赖:在某些实现中需要开发者在代码中添加大量的注解增加了代码复杂性。