SpringBoot整合Swagger3

本文已参与「新人创作礼」活动，一起开启掘金创作之路。

Swagger官网： swagger.io/

借助Swagger，后端开发人员可以省略一大部分用来写接口文档的时间，并且可以无需借助Postman之类的接口调试工具，直接在浏览器调试后端开放的所有接口。

照例，先引入依赖:

<!-- swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

然后定义一个Swagger的配置类:

package com.tct.sms.mtf.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.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @author wl
 * @date 2022/4/18
 */
@Configuration
public class Swagger3Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .groupName("sms-mtf")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.tct.sms.mtf.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("维保填报后端接口文档")
                .description("维保填报后端相关接口描述")
                .version("1.0")
                .build();
    }
}

接着简单了解一下Swagger的常用注解：

注解	注解位置
@Api	Controller 类上
@ApiOperation	Controller 方法上
@ApiImplicitParams	Controller 方法上
@ApiImplicitParam	Controller 方法上 @Parameters 里
@ApiParam	Controller 方法的参数上
@ApiModel	DTO类上
@ApiModelProperty	DTO属性上

根据表格里的注解简单示范几个注解的使用:

作用在实体类上:

package com.tct.sms.mtf.entity;

import com.alibaba.fastjson.annotation.JSONField;
import com.baomidou.mybatisplus.annotation.FieldFill;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import java.util.Date;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import org.springframework.format.annotation.DateTimeFormat;

/**
 *
 * @TableName user
 */
@ApiModel("用户")
@TableName(value ="user")
@Data
public class User{
    /**
     *
     */
    @ApiModelProperty("用户ID")
    @TableId
    private String userId;

    /**
     * 成员名称
     */
    @ApiModelProperty("用户名称")
    @JSONField(name = "name")
    private String userName;

    /**
     * 手机号
     */
    @ApiModelProperty("手机号")
    private String mobile;

    /**
     * 职务
     */
    @ApiModelProperty("职务")
    private String position;

    /**
     * 性别。0表示未定义，1表示男性，2表示女性
     */
    @ApiModelProperty("性别")
    private String gender;

    /**
     * 邮箱
     */
    @ApiModelProperty("邮箱")
    private String email;

    /**
     * 头像
     */
    @ApiModelProperty("头像")
    private String avatar;

    /**
     * 激活状态: 1=已激活，2=已禁用，4=未激活，5=退出企业
     */
    @ApiModelProperty("激活状态")
    private Integer status;

    @ApiModelProperty("创建时间")
    @TableField(fill = FieldFill.INSERT)
    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date createTime;

    @ApiModelProperty("更新时间")
    @TableField(fill = FieldFill.INSERT_UPDATE)
    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date updateTime;
}

作用在controller类上:

package com.tct.sms.mtf.controller;

import com.tct.sms.mtf.common.result.RestResult;
import com.tct.sms.mtf.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author wl
 * @date 2022/5/19
 */
@Api(tags = "用户接口")
@RestController
@RequestMapping("/user")
public class UserController {
    private final UserService userService;

    @Autowired
    public UserController(UserService userService) {
        this.userService = userService;
    }

    @ApiOperation("根据部门查询成员列表")
    @GetMapping("/getByDept")
    public RestResult getByDept(Integer deptId) {
        return RestResult.success(userService.queryByDeptId(deptId));
    }
}

最后启动服务:

启动成功后在浏览器输入接口文档地址: http://localhost:8018/swagger-ui/index.html

注意此处端口要用自己的端口号,我这里启动的服务端口是8018

可以看到这里以controller为单位展示接口列表，点击用户接口：

点击try it out

输入部门ID，点击excute

可以看到接口调用成功了：

借助Swagger的注解，不仅快速生成了接口文档，还可以直接调试，还是非常方便的。