springboot项目集成swagger接口文档

1.描述

springboot集成swagger接口文档方便开发调试、对接前端以及接口后期维护，在尽量少的注解侵入性前提下使用swagger功能，该文档使用swagger2+knife4j第三方UI（PS：至于为啥不用swagger3，博主强迫症被参数排序问题给整吐了。。。）

2.版本信息

springboot版本：2.5.6
swagger版本：2.9.2

knife4j版本：2.0.4

3.pom.xml

<!--swagger2相关依赖-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
    <exclusions>
       <exclusion>
          <groupId>io.swagger</groupId>
          <artifactId>swagger-models</artifactId>
       </exclusion>
    </exclusions>
</dependency>
<!-- 防止进入swagger页面报类型转换错误，排除3.0.0中的引用，手动增加1.6.2版本 -->
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-models</artifactId>
    <version>1.6.2</version>
</dependency>
<!--基于BootStrap的swagger UI框架-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.4</version>
</dependency>

4.配置文件

application.propertie

baseproject.name=base-project
baseproject.version=1.1.0
swagger.enabled=true
swagger.pathMapping=/

 SwaggerConfig.java

package com.bylz.framework.swagger2;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Value;
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.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2配置
 * @author lizhi
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfig
{
    /** 系统基础配置 */
    @Value("${baseproject.name}")
    private String appName;
    @Value("${baseproject.version}")
    private String appVersion;
    /** 是否开启swagger */
    @Value("${swagger.enabled}")
    private boolean enabled;
    /** 设置请求的统一前缀 */
    @Value("${swagger.pathMapping}")
    private String pathMapping;

    /**
     * 创建API
     */
    @Bean
    public Docket createRestApi()
    {
        return new Docket(DocumentationType.SWAGGER_2)
                // 是否启用Swagger
                .enable(enabled)
                // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
                .apiInfo(apiInfo())
                // 设置哪些接口暴露给Swagger展示
                .select()
                // 扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
                .pathMapping(pathMapping);
    }

    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo()
    {
        // 用ApiInfoBuilder进行定制
        return new ApiInfoBuilder()
                // 设置标题
                .title("基础项目-接口文档")
                // 描述
                .description("基础项目封装")
                // 作者信息
                .contact(new Contact(appName, null, null))
                // 版本
                .version(appVersion)
                .build();
    }
}

5.注解使用

controller类注解

package com.bylz.baseproject.controller;

import com.bylz.baseproject.entity.dao.SysUser;
import com.bylz.baseproject.entity.dto.SysUserAddDto;
import com.bylz.baseproject.entity.dto.SysUserListDto;
import com.bylz.baseproject.entity.dto.SysUserUpdDto;
import com.bylz.baseproject.service.SysUserService;
import com.bylz.common.CommonEnum;
import com.bylz.common.ResponseData;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

import javax.annotation.Resource;

/**
 * 用户管理控制层
 * @author lizhi
 * @since 2021-11-23 09:45:16
 */
@RestController
@RequestMapping("/sysUser")
@Api(tags = "2.用户管理")
public class SysUserController {

    @Resource
    private SysUserService sysUserService;

    /**
     * 通过主键查询单条数据
     *
     * @param id 主键
     * @return 单条数据
     */
    @GetMapping("selectOne")
    @ApiOperation(value = "查询用户详情")
    public SysUser selectOne(Long id) {
        return sysUserService.queryById(id);
    }

    /**
     * 新增用户
     * @param sysUserAddDto
     * @return ResponseData
     */
    @PostMapping("/add")
    @ApiOperation(value = "新增用户")
    public ResponseData addUser(@RequestBody SysUserAddDto sysUserAddDto) {
        return ResponseData.success(CommonEnum.SUCCESS.getResultCode(), CommonEnum.SUCCESS.getResultMsg(), sysUserService.addUser(sysUserAddDto));
    }

    /**
     * 编辑用户
     * @param sysUserUpdDto
     * @return ResponseData
     */
    @PutMapping("/upd")
    @ApiOperation(value = "编辑用户")
    public ResponseData updUser(@RequestBody SysUserUpdDto sysUserUpdDto) {
        sysUserService.updUser(sysUserUpdDto);
        return ResponseData.success(CommonEnum.SUCCESS.getResultCode(), CommonEnum.SUCCESS.getResultMsg(), null);
    }

    /**
     * 删除用户
     * @param id
     * @return ResponseData
     */
    @DeleteMapping("/del")
    @ApiOperation(value = "删除用户")
    @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long", dataTypeClass = Long.class, paramType = "query")
    public ResponseData delUser(Long id) {
        sysUserService.delUser(id);
        return ResponseData.success(CommonEnum.SUCCESS.getResultCode(), CommonEnum.SUCCESS.getResultMsg(), null);
    }

    /**
     * 查询用户列表
     * @param sysUserListDto
     * @return ResponseData
     */
    @GetMapping("/list")
    @ApiOperation(value = "用户列表")
    public ResponseData listUser(SysUserListDto sysUserListDto) {
        return ResponseData.success(CommonEnum.SUCCESS.getResultCode(), CommonEnum.SUCCESS.getResultMsg(), sysUserService.listUser(sysUserListDto));
    }

    /**
     * 重置用户密码
     * @param id
     * @return ResponseData
     */
    @GetMapping("/resetPwd")
    @ApiOperation(value = "重置密码")
    @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long", dataTypeClass = Long.class, paramType = "query")
    public ResponseData resetPwd(Long id) {
        return ResponseData.success(CommonEnum.SUCCESS.getResultCode(), CommonEnum.SUCCESS.getResultMsg(), sysUserService.resetPwd(id));
    }

}

dto类注解

package com.bylz.baseproject.entity.dto;

import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.io.Serializable;

/**
 * 新增用户参数
 */
@Data
public class SysUserAddDto implements Serializable {

    private static final long serialVersionUID = 731264681268653572L;

    @ApiModelProperty(value = "用户账号", required = true, position = 1)
    private String userName;
    @ApiModelProperty(value = "用户昵称", required = true, position = 2)
    private String nickName;
    @ApiModelProperty(value = "密码", required = true, position = 3)
    private String password;
    @ApiModelProperty(value = "手机号码", position = 4)
    private String phone;
    @ApiModelProperty(value = "邮箱", position = 5)
    private String email;
    @ApiModelProperty(value = "性别", position = 6)
    private String sex;
    @ApiModelProperty(value = "账号状态", position = 7)
    private String status;
    @ApiModelProperty(value = "部门id", position = 8)
    private Long deptId;
    @ApiModelProperty(value = "多角色id", position = 9)
    private Long[] roleIds;
    @ApiModelProperty(value = "岗位id", position = 10)
    private Long positionId;

}

备注：更多详细注解请参考swagger注解使用！！！

6.效果演示

启动boot项目，访问http://ip:port/doc.html

 备注：如果项目有资源拦截，类似于我项目中有shiro，需要放开swagger资源访问

//静态资源
filterChainDefinitionMap.put("/*.html", "anon");
filterChainDefinitionMap.put("/**/*.html", "anon");
filterChainDefinitionMap.put("/**/*.css", "anon");
filterChainDefinitionMap.put("/**/*.js", "anon");
//swagger
filterChainDefinitionMap.put("/swagger-resources/**", "anon");
filterChainDefinitionMap.put("/swagger-ui/**", "anon");
filterChainDefinitionMap.put("/swagger-ui.html", "anon");
filterChainDefinitionMap.put("/*/api-docs", "anon");
filterChainDefinitionMap.put("/webjars/**", "anon");