SpringBoot3整合SpringDoc实现在线接口文档
写在前面在现目前项目开辟中，一般都是前后端分离项目。前端小姐姐负责开辟前端，苦逼的我们负责后端开辟
事实是一个人全干，在这过程中编写接口文档就显得尤为紧张了。然而作为一个程序员，最怕的莫过于自己写文档和别人不写文档
各人都不想写文档，那这活就交给今天的主角Swagger来实现了
一、专业名词介绍
①OpenApi是什么？
解答：OpenApi是一个用于描述、定义和共享 RESTful API 文档的规范。最新规范是 OpenAPI 3.0
② Swagger是什么？
解答： Swagger 是一个用于设计和测试 RESTful APIs 的工具。
它提供了API 描述、哀求和相应示例、API 测试和文档生成等丰富的功能。最新版本是Swagger3,支持OpenAPI3.0规范
③ SpringFox是什么？
SpringFox 是 Spring 社区维护的一个项目（非官方），资助使用者将 Swagger 2 集成到 Spring 中。
目前国内项目使用的都是它
github地址：https://github.com/springfox/springfox
④springDoc是什么？
解答： Spring-doc也是 Spring 社区维护的一个项目（非官方），资助使用者将 Swagger 3 集成到 Spring 中
SpringDoc 支持 Swagger 页面 Oauth2 登录，相较于 SpringFox 而言，它的支撑时间更长，无疑是更好的选择。
但是在国内发展较慢，网上一找资料，出来的基本上是 Swagger2的内容。
地址：https://springdoc.org/
⑤ OpenAPI 、Spring-doc和 Swagger 之间的关系
解答：OpenAPI 定义了一种标准的格式来体现 API 文档，而 Swagger 是一个实现 OpenAPI 规范的工具
二、Swagger详细简介
Swagger 江湖人称“丝袜哥”，是一个资助程序员生成接口文档的利器。
只必要简单设置，就可以生成带有漂亮UI界面的接口文档，而且编写的接口代码变了
接口文档随之也跟着变，做到了真正的解放双手。
官网https://swagger.io/
Swagger 优点
[*]号称世界上最流行的API框架
[*]Restful Api 文档在线自动生成器
[*]直接运行，支持在线测试API
[*]不仅仅支持Java，还支持多种语言（如：PHP、Python、Node.js等）
三、小试牛刀
说了这么多Swagger 的优点，接下来就小试牛刀，看看怎么将Swagger集成到SpringBoot中。
3.1、环境介绍
[*]JDK：17
[*]SpringBoot：3.3.0
[*]Springdoc
注： 仔细的小伙伴可能已经发现了，在springboot3.0之前我用的都是Springfox来集成Swagger管理我们的API接口文档,
但是Springfox已经停止更新了，我们使用的是SpringBoot3 +jdk17 的环境后，Spring官网保举了Springdoc 来整合swagger
3.2 新建一个springboot-web项目
3.3 添加依赖
由于篇幅原因，其他web项目相干依赖这里就不一一贴出来了。
第一个依赖是必须的，而且版本必须大于2.0.0
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.2.0</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
<version>2.2.0</version>
</dependency>注：
我们这里使用的是jdk17+springboot3.3.0 环境，原来swagger的V2和V3都不能用了，小伙伴们一定更要注意这儿
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738591-1652742861.png
如果引入上面错误的依赖，项目启动会报下面错误，这时候我们引入上面正确的依赖重新启动项目即可
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738572-1437703116.png
3.4 编写HelloController
新建一个controller包--->建立一个HelloController类
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738751-1680986539.png
@RestController
public class HelloController {
@RequestMapping("/hello")
public String hello(){
return "hello";
}
}我们在浏览器中输入“http://localhost:8080/hello” 后回车，出现如下界面，说明我们的hello开辟成功了
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738796-1039326019.png
3.5 访问swagger接口页面
注：我们这里采用的是openapi ,所以就不用像swagger的V2和v3那样添加设置类了
浏览器直接输入：http://localhost:8080/swagger-ui/index.html 回车即可看到下面界面
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738750-575678751.png
整合swagger是不是很简单呢
四、修改接口
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738777-55109151.png
从上面截图中我们看到，我们在HelloController 中只定义了一个接口，但是前端UI界面中出来个7种哀求方式（GET、PUT、POST、DELETE、OPTIONS、HEAD、PATCH）的接口，这是为什么呢？
解答：@RequestMapping("/hello") 我们接口中只是指定了访问地址，并没有指定哀求方式
我们将注解修改成@RequestMapping(path ="/hello",method = RequestMethod.GET)
或者@GetMapping("/hello") 然后重启服务，我们看到界面上就只有一种哀求方式的接口了
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738805-592187850.png
五、接口文档常用设置
5.1 设置访问路径
在application.yml中可以自定义api-docs和swagger-ui的访问路径。当然了，如果没设置，默认就是下面路径
springdoc:
api-docs:
path: /v3/api-docs
swagger-ui:
path: /swagger-ui.html5.2 设置接口文档基本信息
① 设置接口基本信息
新建一个config包--->并在包下建立一个SpringDocConfig设置类
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738596-2010566836.png
② 设置接口文档根本信息
我们在设置类中添加如下代码，
@Configuration
public class SpringDocConfig {
@Bean
public OpenAPI openAPI() {
return new OpenAPI()
// 配置接口文档基本信息
.info(this.getApiInfo())
;
}
private Info getApiInfo() {
return new Info()
// 配置文档标题
.title("SpringBoot3集成Swagger3")
// 配置文档描述
.description("SpringBoot3集成Swagger3示例文档")
// 配置作者信息
.contact(new Contact().name("程序员小凡").url("https://www.xiezhrspace.cn").email("1666397814@163.com"))
// 配置License许可证信息
.license(new License().name("Apache 2.0").url("https://www.xiezhrspace.cn"))
// 概述信息
.summary("SpringBoot3集成Swagger3示例文档aaa")
.termsOfService("https://www.xiezhrspace.cn")
// 配置版本号
.version("2.0");
}
}前端页面访问接口文档页面后显示如下
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738828-1168655517.png
② 设置接口servers信息
接口可能存在多环境，如开辟环境、测试环境、生产环境等
我们可以通过@OpenAPIDefinition 配合servers 属性来设置不同环境，具体设置示例如下
@OpenAPIDefinition(
servers = {
@Server(description = "开发环境服务器", url = "http://localhost:8080"),
@Server(description = "测试环境服务器", url = "https://test.xiezhr.com")
}
)
@Configuration
public class SpringDocConfig {
//...
}设置完成后，浏览器访问显示如下
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738806-5046522.png
③ 设置外部文档信息
有时候我们必要在在线接口文档中可以显示跳转到API的一些外部文档（好比 项目部署文档等）
这个时候我们可以通过@OpenAPIDefinition 配合externalDocs 属性来设置外部文档
具体设置如下
@OpenAPIDefinition(
externalDocs = @ExternalDocumentation(
description = "项目编译部署说明",
url = "http://localhost:8080/deplay/readme.md"
)
)
@Configuration
public class SpringDocConfig {
//......
}设置完后重启服务，浏览器访问接口文档，显示如下
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738837-352373783.png
SpringDocConfig 类完整设置代码如下
@OpenAPIDefinition(
servers = {
@Server(description = "开发环境服务器", url = "http://localhost:8080"),
@Server(description = "测试环境服务器", url = "https://test.xiezhr.com")
},
externalDocs = @ExternalDocumentation(
description = "项目编译部署说明",
url = "http://localhost:8080/deplay/readme.md"
)
)
@Configuration
public class SpringDocConfig {
@Bean
public OpenAPI openAPI() {
return new OpenAPI()
// 配置接口文档基本信息
.info(this.getApiInfo())
;
}
private Info getApiInfo() {
return new Info()
// 配置文档标题
.title("SpringBoot3集成Swagger3")
// 配置文档描述
.description("SpringBoot3集成Swagger3示例文档")
// 配置作者信息
.contact(new Contact().name("程序员小凡").url("https://www.xiezhrspace.cn").email("1666397814@163.com"))
// 配置License许可证信息
.license(new License().name("Apache 2.0").url("https://www.xiezhrspace.cn"))
//
.summary("SpringBoot3集成Swagger3示例文档aaa")
.termsOfService("https://www.xiezhrspace.cn")
// 配置版本号
.version("2.0");
}
}设置完上面信息后，重启服务，浏览器访问：http://localhost:8080/v3/swagger-ui/index.html
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738809-1572527498.png
5.3设置扫描接口
应用场景：
有时候我们为了业务必要，我们建立了多个包下的接口，如admin包下的，common包下的接口，
为了安全起见，我们只答应接口文档中访问comm包下面的接口。
在不加任何设置的情况下，所以接口都会默认显示，具体如下
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738832-2078667840.png
设置扫描接口包：
在application.yml中可以自定义要扫描的接口包
springdoc:
packages-to-scan: com.xiezhr.swaggerdemo.common.controller设置好之后重启服务，我们发现前台UI只显示了common包下面的接口了
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738838-1888104529.png
5.4 设置接口文档开关
使用场景：
为了接口安全，我们一般必要在测试（test）环境或者开辟(dev)环境中开启接口文档，而在生产（prod）环境中 关闭接口文档
这个应该怎么做呢？
这里涉及到SpringBoot多环境设置，忘记的小伙伴可以翻一翻之前的文章。传送门：
我们创建三个设置文件，分别为
[*]① application-dev.yml开辟环境
[*]② application-test.yml 测试环境
[*]③ application-prod.yml 生产环境
只需在①和②设置文件中添加如下设置
springdoc:
api-docs:
enabled: true而③设置文件中添加
springdoc:
api-docs:
enabled: false通过上面设置后，我们在开辟和测试环境下：就能正常访问http://localhost:8080/v3/swagger-ui/index.html#/
而在生产环境下就无法访问，报如下错误
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738854-1267305109.png
5.5 设置API分组
为了演示API分组，我们在controller包下面再建立admin包和common包，包下分别添加AdminController和CommonController接口类,布局及代码如下
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738809-890905715.png
① AdminController类
// AdminController
@RestController
@RequestMapping("/admin")
public class AdminController {
@GetMapping("/index")
public Stringadmin(){
return "admin";
}
}② CommonController 类
@RestController
@RequestMapping("/common")
public class CommonController {
@GetMapping("/hello")
public String hello(){
return "hello";
}
}在默认情况（没有分组）的情况下，全部包下接口都显示在一一个默认组下面，如/common/* 和/admin/* 访问路径下的接口都显示在一起，如下图所示
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738874-722083155.png
这时，如果/common/* 下的接口比力多，/admin/* 下的接口也比力多，界面上显示就很混乱
解决办法就是添加分组信息，我们在SpringDocConfig 设置类中添加如下代码,这样就把接口分为了"common通用模块组" 和"admin模块组" 两个组
@Bean("commonGroupApi")
public GroupedOpenApi webGroupApi() {
return GroupedOpenApi.builder().group("common通用模块组")
.pathsToMatch("/common/**")
.build();
}
@Bean("adminGroupApi")
public GroupedOpenApi adminGroupApi() {
return GroupedOpenApi.builder().group("admin模块组")
.pathsToMatch("/admin/**")
.build();
}重启服务，再访问http://localhost:8080/v3/swagger-ui/index.html如下
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738842-288106660.png
5.6 设置接口信息
① @Tag 注解使用
对一个 operation 进行说明或定义的标签，用在类或方法上，也可以用在 @OpenAPIDefinition 中定义标签。
常用参数：
[*]name: 名称
[*]description: 接口描述信息
示例：
用在类上
@RestController
@RequestMapping("/common")
@Tag(name = "公共接口", description = "公共接口")
public class CommonController {
//......
}② @Operation 注解使用
用于说明方法用途，用在方法上。
参数：
[*]summary：方法概要，方法的一个简单介绍，发起 120 个字符内
[*]description：方法描述，一般是很长的内容
[*]hidden：是否隐藏
示例：
@GetMapping("/hello")
@Operation(summary = "hello接口", description = "hello接口描述" ,hidden = true)
public String hello(){
return "hello";
}③ @Parameter注解使用
用于说明方法参数，用在方法参数上。
参数：
[*]name：指定的参数名
[*]in：参数位置，可选 query、header、path 或 cookie，默认为空，体现忽略
[*]description：参数描述
[*]required：是否必填，默认为 false
示例：
@GetMapping("/user/{id}")
public User getUser( @Parameter(name = "id",in = ParameterIn.PATH,description = "用户ID",required = true) @PathVariable("id") Integer id){
User user = userService.getUserById(id);
return user;
}前端页面查看
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738621-1806259248.png
④ @ApiResponse 注解使用
用于说明一个相应信息，用在 @ApiResponses 中。
参数：
[*]responseCode：HTTP 相应码
[*]description：描述
示例：
@GetMapping("/user/{id}")
@Operation(summary = "获取用户信息", description = "根据用户ID获取用户信息")
@ApiResponses(value ={
@ApiResponse(responseCode = "200", description = "请求成功"),
@ApiResponse(responseCode = "404", description = "用户不存在")
})
public User getUser( @Parameter(name = "id",in = ParameterIn.PATH,description = "用户ID",required = true) @PathVariable("id") Integer id){
User user = userService.getUserById(id);
return user;
}https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738830-1485666122.png
完整设置
@RestController
@RequestMapping("/common")
@Tag(name = "公共接口", description = "公共接口")
public class CommonController {
@Autowired
private IUserService userService;
@GetMapping("/hello")
@Operation(summary = "hello接口", description = "hello接口描述" ,hidden = true)
public String hello(){
return "hello";
}
@GetMapping("/hi")
@Operation(summary = "hi接口", description = "hi接口描述")
public String Hi(){
return "Hi 程序员小凡";
}
@GetMapping("/user/{id}")
@Operation(summary = "获取用户信息", description = "根据用户ID获取用户信息")
@ApiResponses(value ={
@ApiResponse(responseCode = "200", description = "请求成功"),
@ApiResponse(responseCode = "404", description = "用户不存在")
})
public User getUser( @Parameter(name = "id",in = ParameterIn.PATH,description = "用户ID",required = true) @PathVariable("id") Integer id){
User user = userService.getUserById(id);
return user;
}
}重启后，浏览器访问http://localhost:8080/v3/swagger-ui/index.html 如下
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738780-2106491506.png
5.7 设置实体信息
① 新建一个User实体类
@Data
public class User {
private String name;
private Integer age;
private String email;
private String address;
}② @Schema标签使用
用于描述数据对象信息或数据对象属性，好比各种POJO类及属性，用在类或类属性上。
参数：
[*]name：属性名称
[*]description：属性描述
[*]required：是否必须
[*]minLength：字符最小长度
[*]maxLength：字符最大长度
③使用示例：
@Data
@Schema(description = "用户实体类",name = "User")
public class User {
@Schema(description = "用户名",name ="name",minLength =6,maxLength = 20,required = true)
private String name;
@Schema(description = "年龄",name ="age",required = true,minimum = "1",maximum = "100")
private Integer age;
@Schema(description = "邮箱",name ="email",required = true)
private String email;
@Schema(description = "地址",name ="address")
private String address;
}④ 浏览器访问：http://localhost:8080/v3/swagger-ui/index.html ，我们看到设置的实体信息显示出来了
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738847-997248528.png
六、接口调试
通过上面各种设置之后，我们的在线接口文档基本上生成得差不多了。接下来我们就来说说怎么使用在线接口文档进行接口测试
① 测试说明
在之前末节中我们开辟了要给根据用户ID 获取用户信息的接口getUser。我们现在要做的就是在前端UI界面中找到这个接口，
在开辟环境下输入用户ID值，然后获取用户信息。
② 选择组信息
【获取用户信息】这个接口在，common通用模块组下面，所以我们第一步就要前端UI界面右上角选择这个组
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738799-1264688452.png
② 选择开辟环境
在Servers 下选择设置好的开辟环境
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738594-1016371166.png
③ 找到我们要测试的接口
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738777-1641074020.png
④ 测试接口，获取相应数据
接口右边下三角箭头展开接口------>点击Try it out
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738850-1175692539.png
输入参数：用户ID------> 点击【Execute】----->在Response body 中查看接口相应信息
https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738808-992439633.png
七、添加哀求头
很多时候我们接口都必要认证之后才气访问，这时候我们就必要接口调用的时候携带着Token信息
示例：
我们通过@RequestHeader注解 获取哀求头中token信息
@GetMapping("/index")
public Stringadmin(@RequestHeader ("token") String token){
System.out.println("token>>>>>>>>>>>>>>>>>>>>>>>>"+token);
//token 验证
//.....各种业务逻辑
return "admin";
}https://img2024.cnblogs.com/blog/2381533/202406/2381533-20240617215738619-1740452466.png
到此，本期内容就结束了，★,°:.☆(￣▽￣)/$:.°★ 。希望对您有所资助
我们下期再见 ヾ(•ω•`)o (●'◡'●)
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。
页:
[1]