四、接入Swagger接口文档
这个Swagger我以前写过这篇文章，这里为了教程的完整性，我将那边的内容再放到这里来说一下，结合我们的项目进行整合。
1、什么是Swagger？
做为一个后端开发人员或者是前端开发人员，总归是要沟通调试项目的，前端要接口数据，不知道接口地址，我总不能一个一个的把接口地址发给他吧，前端可能要打人了，后端觉得编写及维护接口文档会耗费不少精力，所以双方经常抱怨，经常扯皮，有这时间摸摸鱼不好嘛，所以Swagger就来接手这个重任，将项目的接口进行管理。所以前端只需要这一份接口文档就可以拿到数据，进行数据的处理等。提高开发效率。
1.1、Swagger介绍
官方网址：Swagger官网
1.2、使用Swagger的好处
● 无依赖
UI 适用于任何开发环境，无论是本地还是 Web。
● 人性化
允许最终开发人员轻松交互并尝试您的 API 公开的每一个操作，以便于使用。
● 易于导航
使用分类整齐的文档快速查找和使用资源和端点。
● 所有浏览器支持
通过适用于所有主要浏览器的 Swagger UI 迎合所有可能的场景。
● 完全可定制的
样式并通过完整的源代码访问以您想要的方式调整您的 Swagger UI。
● 完整的 OAS 支持
可视化 Swagger 2.0 或 OAS 3.0 中定义的 API。
2、项目中如何载入Swagger？
说到这，有人会问，该如何把Swagger引用到项目中呢，不会是YY意想的吧，肯定不是，只需要导个包就可以了。有人又问：在哪导包，导什么包？我来告诉你，就在项目的pom.xml中，复制粘贴以下代码，就完成了Swagger加载到项目中了。
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>
添加完，等待下载完包即可。此时Swagger已经加入了项目中。
3、如何使用Swagger？
准备工作结束啦，那如何使用呢？是啊，如何使用啊，有人说：接口文档肯定要在接口使用，我转身给你一个大大的赞，说的太对了，最主要的作用就是在接口上使用。接下来跟我来学习如何使用。
3.1、接口归类
首先我们在Controller类上加入一个Swagger注解：@Api主要是描述这个Controller是哪一个模块的接口，分类明确。假如是用户的接口类。那么这个类会有对用户的增删改查不同的方法。
@Api(tags = "用户管理") //每个Controller上加上一个@Api注解 @RestController @RequestMapping("/user") public class UserController { }
3.2、接口方法
大的分类标注好了，下面则是每个接口方法的标题，我们在每个方法的上面添加一个@ApiOperation注解，描述这个接口方法的功能，是删除还是修改或者添加等。
UserController.java完整代码：
package com.blog.personalblog.controller; import cn.hutool.core.util.StrUtil; import com.blog.personalblog.util.JsonResult; import com.blog.personalblog.entity.User; import com.blog.personalblog.service.UserService; import com.blog.personalblog.util.MD5Util; import com.blog.personalblog.util.PhoneUtil; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.*; import javax.validation.Valid; import java.util.List; /** * @author: SuperMan * 欢迎关注我的公众号：码上言 * @create: 2021-11-03 */ @Api(tags = "用户管理") @RestController @RequestMapping("/user") public class UserController { @Autowired UserService userService; /** * 用户列表 * @return */ @ApiOperation(value = "用户列表") @PostMapping("/list") public JsonResult<Object> list() { List<User> userList = userService.findAll(); return JsonResult.success(userList); } /** * 添加用户 * @return */ @ApiOperation(value = "添加用户") @PostMapping("/create") public JsonResult<Object> userCreate(@RequestBody @Valid User user) { if (StrUtil.isEmpty(user.getPassWord())) { return JsonResult.error("密码为空，请填写密码！"); } //密码加密存储 user.setPassWord(MD5Util.MD5(user.getPassWord())); //判断手机号，这里用hutool工具类也可以 if (!PhoneUtil.checkMobile(user.getPhone())) { return JsonResult.error("手机号码格式错误！"); } userService.createUser(user); return JsonResult.success(); } /** * * 修改用户 * @return */ @ApiOperation(value = "修改用户") @PostMapping("/update") public JsonResult<Object> userUpdate(@RequestBody @Valid User user) { if (StrUtil.isEmpty(user.getPassWord())) { return JsonResult.error("密码为空，请填写密码！"); } //密码加密存储 user.setPassWord(MD5Util.MD5(user.getPassWord())); //判断手机号，这里用hutool工具类也可以 if (!PhoneUtil.checkMobile(user.getPhone())) { return JsonResult.error("手机号码格式错误！"); } userService.updateUser(user); return JsonResult.success(); } /** * 删除 * @return */ @ApiOperation(value = "删除用户") @PostMapping("/delete/{id}") public JsonResult<Object> userDelete(@PathVariable(value = "id") int id) { userService.deleteUser(id); return JsonResult.success(); } }
到此，你以为就这样好了吗？没错，这就好了，此时我们启动项目，我们的项目是localhost:8081/blog地址，然后加上Swagger的路径。
点击http://localhost:8081/blog/swagger-ui/index.html则会出现以下界面。
看到了吧，有我刚才加的接口标签。此时Swagger添加好了，就可以正常的使用了。
4、配置Swagger
以上的步骤Swagger可以用了，但是为了项目的规范化，我们可以对这个页面进行改造，版本、指定controller包等操作。
我们在config配置包中新建一个Swagger3Config.java的配置类。
package com.blog.personalblog.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.oas.annotations.EnableOpenApi; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; /** * @author: SuperMan * 欢迎关注我的公众号：码上言 * @create: 2021-11-15 */ @Configuration @EnableOpenApi public class Swagger3Config { @Bean public Docket docket(){ return new Docket(DocumentationType.OAS_30) .apiInfo(apiInfo()).enable(true) .select() //添加swagger接口提取范围,修改成指向你的controller包 .apis(RequestHandlerSelectors.basePackage("com.blog.personalblog.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo(){ return new ApiInfoBuilder() .title("个人博客系统接口文档") .description("个人博客系统") .contact(new Contact("码上言", "https://xyhwh.gitee.io/blog/", "作者Email")) .version("1.0") .build(); } }
这些没什么好说的，需要注意的是要指向你项目的controller包，下面的则是配置一些你接口文档的信息。
配置完，重启项目，还是访问原来的地址：http://localhost:8081/blog/swagger-ui/index.html
看，接口文档中出现了我们配置的信息，是不是感觉有点高大上的感觉，我们的项目也有了接口文档，前端直接拿这个接口文档就可以开发了，我们更新只需要重启下项目即可，但是这个文档在我们上线发布的时候要去掉，保证系统的信息安全。
好啦，以上就是我们所讲述的知识，这些虽然看着很零散，但都是项目刚开始最基础的东西，基本上都可以用得到，非常的方便。但对于我们本项目前后端都是我们自己搞就不太需要那么规范，但我们尽量按照开发规范来开发，养成好习惯。
