基于SpringBoot3从零配置SpringDoc
一、SpringFox
- github SpringFox 已经停止更新了。
- SpringFox 对 SpringBoot3.0 不适配,要使用必须降低 SpringBoo t版本。
二、SpringDoc
参考文章 ===> 基于SpringBoot3从零配置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 规范官方文档
四、SpringBoot3配置Knife4j
- Knife4j 是一个集 Swagger2 和 OpenAPI3 为一体的增强解决方案。Knife4j 相当于是对 SpringDoc UI 优化的一个组件。
- Knife4j就是一个接口文档工具,可以看作是Swagger的升级版,但是界面比Swagger更好看,功能更丰富。
1.官方参考文档
- 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.添加配置项
- 官方文档(详细配置):
server.port: 8800 # 设置端口号
server:
servlet:
context-path: /test # 设置dispatcher访问的路径
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: true
username: admin
password: 123456
setting: # 前端UI的个性化配置属性
language: zh_cn # 显示语言中文
enable-version: true
enable-swagger-models: true # 是否显示界面中SwaggerModel功能
swagger-model-name: SwaggerModel2 # 重命名SwaggerModel名称,默认
enable-document-manage: true # 是否显示界面中"文档管理"功能
4.设置文档首页
import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class Knife4jConfig {
@Bean
public OpenAPI myOpenAPI() {
return new OpenAPI()
// 接口文档标题
.info(new Info().title("程序员API")
// 接口文档简介
.description("这是基于Knife4j OpenApi3的接口文档")
.termsOfService("https://blog.csdn.net/weixin_65032328?type=blog")
// 接口文档版本
.version("v1.0.0")
// 接口文档协议
.license(new License()
.name("许可协议")
.url("https://blog.csdn.net/weixin_65032328?type=blog"))
// 开发者联系方式
.contact(new Contact()
.name("迷人的小宝")
.email("dingbaogui8@gmail.com")
.url("https://blog.csdn.net/weixin_65032328?type=blog")))
.externalDocs(new ExternalDocumentation()
.description("小宝945博客")
.url("https://blog.csdn.net/weixin_65032328?type=blog"));
}
}
5.编写控制器
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
@Tag(name = "项目首页", description = "用户首先访问的页面")
@RestController
public class HelloController {
@Parameters ({
//详细说明每一个参数
@Parameter(name = "name", description = "请求人姓名", required = true)
})
@Operation (summary = "简短描述", description = "更详细的描述")
@PostMapping("/calldingbao")
public String hello(String name){
return name + "好啊,我是xiu宝哦!!!";
}
}
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/user")
@Tag(name = "用户管理", description = "用户数据增删改查")
public class UserController {
@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}")
public Integer getUserById(@PathVariable int id) {
return id;
}
}
6.文档展示
- 此时运行项目,例如:http://127.0.0.1:8080/test/doc.html