基于SpringBoot3从零配置SpringDoc

基于SpringBoot3从零配置SpringDoc

一、SpringFox

• github SpringFox 已经停止更新了。
• SpringFox 对 SpringBoot3.0 不适配，要使用必须降低 SpringBoot的版本。

二、SpringDoc

• SpringDoc，它可简化 API 文档的生成和维护，这些文档基于 OpenAPI 3 规范，适用于 Spring Boot 3.x 应用程序。Spring Boot 3.x 要求使用 springdoc-openapi version 2 及以上。<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.1.0</version></dependency>

三、Open API 规范

• Open API 即开放 API，也称开放平台。 所谓的开放 API（OpenAPI）是服务型网站常见的一种应用，网站的服务商将自己的网站服务封装成一系列 API（Application Programming Interface，应用编程接口）开放出去，供第三方开发者使用，这种行为就叫做开放网站的 API，所开放的 API 就被称作 OpenAPI（开放 API ）。
• OpenAPI 规范官方文档 - https://openapi.apifox.cn/

四、SpringBoot3配置Knife4j

• Knife4j 是一个集 Swagger2 和 OpenAPI3 为一体的增强解决方案。Knife4j 相当于是对 SpringDoc UI 优化的一个组件。
• Knife4j就是一个接口文档工具，可以看作是Swagger的升级版，但是界面比Swagger更好看，功能更丰富。

1.官方参考文档

• Knife4j官方网站 - https://doc.xiaominfo.com/
• 官方文档（快速开始） - 快速开始
• 官方文档（Knife4j版本参考） - Knife4j 版本参考

2.添加依赖

<!-- 生成 API 接口文档的组件 --><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.4.0</version></dependency>

3.添加配置项

• 官方文档（详细配置）： - 3.1 增强模式server.port:8800# 设置端口号server:servlet:context-path: /test # 设置服务器的访问路径springdoc:swagger-ui:path: /swagger-ui.html tags-sorter: alpha operations-sorter: alpha api-docs:path: /v3/api-docs group-configs:-group: test paths-to-match:'/**'# 生成文档所需的扫包路径，一般为启动类目录packages-to-scan: com.gdb.test#knife4j 增强配置knife4j:#是否启用增强设置enable:true#开启生产环境屏蔽production:false#是否启用登录认证basic:enable:trueusername: admin password:123456setting:# 前端UI的个性化配置属性language: zh_cn # 显示语言中文enable-version:trueenable-swagger-models:true# 是否显示界面中SwaggerModel功能swagger-model-name: SwaggerModel2 # 重命名SwaggerModel名称,默认enable-document-manage:true# 是否显示界面中"文档管理"功能

4.设置文档首页

importio.swagger.v3.oas.models.ExternalDocumentation;importio.swagger.v3.oas.models.OpenAPI;importio.swagger.v3.oas.models.info.Contact;importio.swagger.v3.oas.models.info.Info;importio.swagger.v3.oas.models.info.License;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;@ConfigurationpublicclassKnife4jConfig{@BeanpublicOpenAPImyOpenAPI(){returnnewOpenAPI()// 接口文档标题.info(newInfo().title("程序员API")// 接口文档简介.description("这是基于Knife4j OpenApi3的接口文档").termsOfService("https://blog.csdn.net/weixin_65032328?type=blog")// 接口文档版本.version("v1.0.0")// 接口文档协议.license(newLicense().name("许可协议").url("https://blog.csdn.net/weixin_65032328?type=blog"))// 开发者联系方式.contact(newContact().name("迷人的小宝").email("[email protected]").url("https://blog.csdn.net/weixin_65032328?type=blog"))).externalDocs(newExternalDocumentation().description("小宝945博客").url("https://blog.csdn.net/weixin_65032328?type=blog"));}}

5.编写控制器

importio.swagger.v3.oas.annotations.Operation;importio.swagger.v3.oas.annotations.Parameter;importio.swagger.v3.oas.annotations.Parameters;importio.swagger.v3.oas.annotations.tags.Tag;importorg.springframework.web.bind.annotation.PostMapping;importorg.springframework.web.bind.annotation.RestController;@Tag(name ="项目首页", description ="用户首先访问的页面")@RestControllerpublicclassHelloController{@Parameters({//详细说明每一个参数@Parameter(name ="name", description ="请求人姓名", required =true)})@Operation(summary ="简短描述", description ="更详细的描述")@PostMapping("/calldingbao")publicStringhello(String name){return name +"好啊，我是xiu宝哦！！！";}}

importio.swagger.v3.oas.annotations.Operation;importio.swagger.v3.oas.annotations.Parameter;importio.swagger.v3.oas.annotations.enums.ParameterIn;importio.swagger.v3.oas.annotations.media.Content;importio.swagger.v3.oas.annotations.responses.ApiResponse;importio.swagger.v3.oas.annotations.tags.Tag;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.PathVariable;importorg.springframework.web.bind.annotation.RequestMapping;importorg.springframework.web.bind.annotation.RestController;@RestController@RequestMapping("/user")@Tag(name ="用户管理", description ="用户数据增删改查")publicclassUserController{@Operation(
            summary ="根据ID，查询用户",
            parameters ={@Parameter(name ="id", description ="用户的唯一标识 id", required =true, in =ParameterIn.PATH)},
            responses ={@ApiResponse(responseCode ="200", description ="成功", content =@Content(mediaType ="application/json")),@ApiResponse(responseCode ="400", description ="错误", content =@Content(mediaType ="application/json"))})@GetMapping("/{id}")publicIntegergetUserById(@PathVariableint id){return id;}}

6.文档展示

• 此时运行项目，例如：http://127.0.0.1:8080/test/doc.html

五、参考

[1]. 基于SpringBoot3从零配置SpringDoc
[2]. Swagger3 GET请求，使用对象接收 Query 参数，注解怎么写？