Spring Boot + vue-element 开发个人博客项目实战教程(十、调试、密码加密和Swagger接口文档)(下)

简介: Spring Boot + vue-element 开发个人博客项目实战教程(十、调试、密码加密和Swagger接口文档)(下)

四、接入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

看,接口文档中出现了我们配置的信息,是不是感觉有点高大上的感觉,我们的项目也有了接口文档,前端直接拿这个接口文档就可以开发了,我们更新只需要重启下项目即可,但是这个文档在我们上线发布的时候要去掉,保证系统的信息安全。


好啦,以上就是我们所讲述的知识,这些虽然看着很零散,但都是项目刚开始最基础的东西,基本上都可以用得到,非常的方便。但对于我们本项目前后端都是我们自己搞就不太需要那么规范,但我们尽量按照开发规范来开发,养成好习惯。

目录
相关文章
|
4天前
|
JavaScript Java 测试技术
基于SpringBoot+Vue的招投标管理系统的详细设计和实现(源码+lw+部署文档+讲解等)
基于SpringBoot+Vue的招投标管理系统的详细设计和实现(源码+lw+部署文档+讲解等)
36 14
|
4天前
|
JavaScript Java 测试技术
基于SpringBoot+Vue的母婴全程服务管理系统的详细设计和实现(源码+lw+部署文档+讲解等)
基于SpringBoot+Vue的母婴全程服务管理系统的详细设计和实现(源码+lw+部署文档+讲解等)
39 17
|
3天前
|
JavaScript Java 测试技术
基于SpringBoot+Vue的公考客观题复习系统的详细设计和实现(源码+lw+部署文档+讲解等)
基于SpringBoot+Vue的公考客观题复习系统的详细设计和实现(源码+lw+部署文档+讲解等)
12 1
|
3天前
|
JavaScript Java 测试技术
基于SpringBoot+Vue的新能源汽车信息咨询服务的详细设计和实现(源码+lw+部署文档+讲解等)
基于SpringBoot+Vue的新能源汽车信息咨询服务的详细设计和实现(源码+lw+部署文档+讲解等)
9 0
|
3天前
|
JavaScript Java 测试技术
基于SpringBoot+Vue的校园菜鸟驿站管理系统的详细设计和实现(源码+lw+部署文档+讲解等)
基于SpringBoot+Vue的校园菜鸟驿站管理系统的详细设计和实现(源码+lw+部署文档+讲解等)
9 0
|
3天前
|
JavaScript Java 测试技术
基于SpringBoot+Vue的毕业设计选题管理系统的详细设计和实现(源码+lw+部署文档+讲解等)
基于SpringBoot+Vue的毕业设计选题管理系统的详细设计和实现(源码+lw+部署文档+讲解等)
8 0
|
3天前
|
JavaScript Java 测试技术
基于SpringBoot+Vue的电影院选票系统的详细设计和实现(源码+lw+部署文档+讲解等)
基于SpringBoot+Vue的电影院选票系统的详细设计和实现(源码+lw+部署文档+讲解等)
6 0
|
3天前
|
JavaScript Java 测试技术
基于SpringBoot+Vue的自助甜品网站的详细设计和实现(源码+lw+部署文档+讲解等)
基于SpringBoot+Vue的自助甜品网站的详细设计和实现(源码+lw+部署文档+讲解等)
5 0
|
3天前
|
JavaScript Java 测试技术
基于SpringBoot+Vue的茶叶销售系统的详细设计和实现(源码+lw+部署文档+讲解等)
基于SpringBoot+Vue的茶叶销售系统的详细设计和实现(源码+lw+部署文档+讲解等)
7 0
|
3天前
|
JavaScript Java 测试技术
基于SpringBoot+Vue的酒店管理系统的详细设计和实现(源码+lw+部署文档+讲解等)
基于SpringBoot+Vue的酒店管理系统的详细设计和实现(源码+lw+部署文档+讲解等)
10 1