### 写在前面在现目前项目开发中，一般都是前后端分离项目。~~前端小姐姐负责开发前端，苦逼的我们负责后端开发~~。事实是一个人全干，在这过程中编写接口文档就显得尤为重要了。然而作为一个程序员，最怕的莫过于自己写文档和别人不写文档。大家都不想写文档，那这活就交给今天的主角`Swagger`来实现了。 ### 一、专业名词介绍 **①`OpenApi`是什么？** **解答：** `OpenApi`是一个用于描述、定义和共享 `RESTful API`文档的规范。最新规范是 `OpenAPI 3.0` **② `Swagger`是什么？** **解答：** `Swagger` 是一个用于设计和测试 `RESTful APIs` 的工具。它提供了`API` 描述、请求和响应示例、`API` 测试和文档生成等丰富的功能。最新版本是`Swagger3`,支持`OpenAPI3.0`规范 **③ `SpringFox` 是什么？** `SpringFox` 是 Spring 社区维护的一个项目（非官方），帮助使用者将 Swagger 2 集成到 Spring 中。目前国内项目使用的都是它 github地址： **④`springDoc`是什么？** **解答：** `Spring-doc`也是 Spring 社区维护的一个项目（非官方），帮助使用者将 Swagger 3 集成到 Spring 中 `SpringDoc` 支持 `Swagger` 页面 `Oauth2` 登录，相较于 `SpringFox` 而言，它的支撑时间更长，**无疑是更好的选择**。但是在国内发展较慢，网上一找资料，出来的基本上是 `Swagger2`的内容。地址： **⑤ `OpenAPI` 、`Spring-doc`和 `Swagger` 之间的关系** **解答：** `OpenAPI` 定义了一种标准的格式来表示 `API` 文档，而 `Swagger` 是一个实现`OpenAPI` 规范的工具 ### 二、Swagger详细简介 Swagger 江湖人称“丝袜哥”，是一个帮助程序员生成接口文档的利器。只需要简单配置，就可以生成带有漂亮`UI`界面的接口文档，而且编写的接口代码变了接口文档随之也跟着变，做到了真正的解放双手。官网 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 ``` org.springdoc springdoc-openapi-starter-webmvc-ui 2.2.0 org.springdoc springdoc-openapi-starter-webmvc-api 2.2.0 ``` **注：** 我们这里使用的是`jdk17+springboot3.3.0` 环境，**原来`swagger`的`V2`和`V3`都不能用了**，小伙伴们一定更要注意这儿 ![不能引入的依赖](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/d58f3ed8fd4e4258ab6bc7a51484d857~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=618&h=304&s=26939&e=png&b=f8f8f8) 如果引入上面错误的依赖，项目启动会报下面错误，这时候我们引入上面正确的依赖重新启动项目即可 ![报错信息](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/15cd96b76148476e9eed5cbaec249ed8~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=990&h=149&s=35351&e=png&b=2c2c2c) #### 3.4 编写`HelloController` 新建一个`controller`包--->建立一个`HelloController`类 ![新建Hellocontroller](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/276938df6b37425eb73f97f17cb4fe07~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=340&h=306&s=13464&e=png&b=3c3f41) ``` @RestController public class HelloController { @RequestMapping("/hello") public String hello(){ return "hello"; } } ``` 我们在浏览器中输入“” 后回车，出现如下界面，说明我们的hello开发成功了 ![hello接口正常访问](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/557154c89b29488394d75bf1b181a792~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=658&h=207&s=8789&e=png&b=ffffff) #### 3.5 访问swagger接口页面 **注**：我们这里采用的是`openapi` ,所以就不用像`swagger`的`V2`和`v3`那样添加配置类了浏览器直接输入：回车即可看到下面界面 ![接口信息](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/56408c4513504668994643f340de8be0~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1429&h=970&s=67643&e=png&b=fbf8f8) 整合swagger是不是很简单呢 ### 四、修改接口 ![多种请求方式](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/bedbdbab1d504f6faaa2179fe1b8c847~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1421&h=455&s=18117&e=png&b=f9f3f2) 从上面截图中我们看到，我们在`HelloController` 中只定义了一个接口，但是前端`UI`界面中出来个7种请求方式（`GET`、`PUT`、`POST`、`DELETE`、`OPTIONS`、`HEAD`、`PATCH`）的接口，这是为什么呢？ **解答：** `@RequestMapping("/hello")` 我们接口中只是指定了访问地址，并没有指定请求方式我们将注解修改成`@RequestMapping(path = "/hello",method = RequestMethod.GET)` 或者`@GetMapping("/hello")` 然后重启服务，我们看到界面上就只有一种请求方式的接口了 ![get请求方式](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/26fe86b3303342ed9c0ac5ea4cbe7553~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1227&h=492&s=27495&e=png&b=fbfbfb) ### 五、接口文档常用配置 #### 5.1 配置访问路径在`application.yml`中可以自定义`api-docs`和`swagger-ui`的访问路径。当然了，如果没配置，默认就是下面路径 ``` springdoc: api-docs: path: /v3/api-docs swagger-ui: path: /swagger-ui.html ``` #### 5.2 配置接口文档基本信息 ① 配置接口基本信息新建一个`config`包--->并在包下建立一个`SpringDocConfig`配置类 ![新建配置类](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/b9caea028e4d40bea0cc639b544ac4e4~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=338&h=306&s=13531&e=png&b=3c3f41) ② 配置接口文档基础信息我们在配置类中添加如下代码， ``` @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://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/3b141e0052fe4181a642176714702ce4~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=740&h=265&s=33645&e=png&b=fafafa) ② 配置接口servers信息接口可能存在多环境，如开发环境、测试环境、生产环境等我们可以通过`@OpenAPIDefinition` 配合`servers` 属性来配置不同环境，具体配置示例如下 ``` @OpenAPIDefinition( servers = { @Server(description = "开发环境服务器", url = "http://localhost:8080"), @Server(description = "测试环境服务器", url = "https://test.xiezhr.com") } ) @Configuration public class SpringDocConfig { //... } ``` 配置完成后，浏览器访问显示如下 ![配置servers信息](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/4ce91a65226c47338e3693917591c676~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1631&h=654&s=58056&e=png&b=fafafa) ③ 配置外部文档信息有时候我们需要在在线接口文档中可以显示跳转到API的一些外部文档（比如项目部署文档等）这个时候我们可以通过`@OpenAPIDefinition` 配合`externalDocs` 属性来配置外部文档具体配置如下 ``` @OpenAPIDefinition( externalDocs = @ExternalDocumentation( description = "项目编译部署说明", url = "http://localhost:8080/deplay/readme.md" ) ) @Configuration public class SpringDocConfig { //...... } ``` 配置完后重启服务，浏览器访问接口文档，显示如下 ![外部API文档](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/bfc8b933b4714234ad075c69f8ea396a~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=966&h=380&s=40189&e=png&b=fafafa) `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"); } } ``` 配置完上面信息后，重启服务，浏览器访问： ![接口文档基本信息](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/e97996422b8b4cf2b3eb89e6e078785c~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1599&h=631&s=77506&e=png&b=fbfbfb) #### 5.3 配置扫描接口 **应用场景：** 有时候我们为了业务需要，我们建立了多个包下的接口，如admin包下的，common包下的接口，为了安全起见，我们只允许接口文档中访问comm包下面的接口。在不加任何配置的情况下，所以接口都会默认显示，具体如下 ![显示所有接口](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/18681ea517a94cd1a51830f6aa87e28d~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1454&h=276&s=18653&e=png&b=fafafa) **配置扫描接口包：** 在`application.yml`中可以自定义要扫描的接口包 ``` springdoc: packages-to-scan: com.xiezhr.swaggerdemo.common.controller ``` 配置好之后重启服务，我们发现前台UI只显示了common包下面的接口了 ![只显示common包下面的接口](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/f8191ea323f74182af9a90bd112b7f7b~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1442&h=203&s=13864&e=png&b=fafafa) #### 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 ``` 通过上面配置后，我们在开发和测试环境下：就能正常访问而在生产环境下就无法访问，报如下错误 ![生产环境](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/2c4ab92f105240d39ce0b9b4d81232ae~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=712&h=262&s=22128&e=png&b=ffffff) #### 5.5 配置API分组为了演示API分组，我们在`controller`包下面再建立`admin`包和`common`包，包下分别添加`AdminController`和`CommonController`接口类,结构及代码如下 ![包结构](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/1d3c58c9807044e9b74c0a2c0b553495~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=310&h=113&s=4757&e=png&b=3c3f41) ①`AdminController`类 ``` // AdminController @RestController @RequestMapping("/admin") public class AdminController { @GetMapping("/index") public String admin(){ return "admin"; } } ``` ② `CommonController` 类 ``` @RestController @RequestMapping("/common") public class CommonController { @GetMapping("/hello") public String hello(){ return "hello"; } } ``` 在默认情况（没有分组）的情况下，所有包下接口都显示在一一个默认组下面，如/common/* 和/admin/* 访问路径下的接口都显示在一起，如下图所示 ![默认分组](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/392df39bb30846f69d635f3a302bc40d~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1608&h=839&s=69572&e=png&b=fbfbfb) 这时，如果/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(); } ``` 重启服务，再访问如下 ![API分组](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/663e5cd6db49461796d3221e9f2da69c~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1799&h=822&s=91074&e=png&b=fbfbfb) #### 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; } ``` 前端页面查看 ![@Paramter注解配置信息](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/0c05292c909b48bc9f59a65d40b604c8~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1442&h=487&s=23704&e=png&b=edf5fb) ④ **`@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; } ``` ![@ApiResponse注解配置信息](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/6924bc1bcb324050bb09749fb43f4728~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1424&h=692&s=45988&e=png&b=ecf4fb) 完整配置 ``` @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; } } ``` 重启后，浏览器访问如下 ![image-20240615213336423](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/0f7317940c574c5eb9adca7cf3d3cd20~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1184&h=894&s=55010&e=png&b=edf5fb) #### 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; } ``` ④ 浏览器访问：，我们看到配置的实体信息显示出来了 ![实体信息](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/dba3daf1bfe04465bcdcf806f7a2fbf4~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1504&h=754&s=25659&e=png&b=f5f5f5) ### 六、接口调试通过上面各种配置之后，我们的在线接口文档基本上生成得差不多了。接下来我们就来说说怎么使用在线接口文档进行接口测试 **① 测试说明** 在之前小节中我们开发了要给根据用户ID 获取用户信息的接口`getUser`。我们现在要做的就是在前端UI界面中找到这个接口，在开发环境下输入用户ID值，然后获取用户信息。 **② 选择组信息** 【获取用户信息】这个接口在，common通用模块组下面，所以我们第一步就要前端UI界面右上角选择这个组 ![选择common通用模块组](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/14676651d50942259c98740bf0649948~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=650&h=117&s=10269&e=png&b=eeeeee) **② 选择开发环境** 在`Servers` 下选择配置好的开发环境 ![选择开发环境](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/3f3a8795a84341abaef591903df3a0a4~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=438&h=142&s=13760&e=png&b=f5f5f5) ③ **找到我们要测试的接口** ![找到目标接口](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/a88f4d505a4b4c8091991cd113a15386~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1446&h=201&s=13564&e=png&b=f7f7f7) ④ 测试接口，获取响应数据接口右边下三角箭头展开接口------>点击`Try it out` ![点击Try it out](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/b0aa8e57389d4583a33e8e7c8046599c~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1421&h=416&s=14019&e=png&b=ecf4fa) 输入参数：用户ID------> 点击【Execute】----->在Response body 中查看接口响应信息 ![根据用户id获取到响应信息](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/3766e4a2d3544a88b326b93b4063dd53~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1403&h=779&s=37669&e=png&b=edf5fb) ### 七、添加请求头很多时候我们接口都需要认证之后才能访问，这时候我们就需要接口调用的时候携带着`Token`信息示例：我们通过`@RequestHeader` 注解获取请求头中`token`信息 ``` @GetMapping("/index") public String admin(@RequestHeader ("token") String token){ System.out.println("token>>>>>>>>>>>>>>>>>>>>>>>>"+token); //token 验证 //.....各种业务逻辑 return "admin"; } ``` ![添加请求头信息](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/e05dfecf89fb420887cacda280834e5e~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1443&h=909&s=51052&e=png&b=edf5fb) 到此，本期内容就结束了，*★,°*:.☆(￣▽￣)/$: *.°★* 。希望对您有所帮助我们下期再见ヾ(•ω•`)o (●'◡'●)