springboot集成swagger2生成文档（使用swagger-bootstrap-ui美化）

springboot集成swagger2生成文档

集成步骤

直接上集成步骤：

1. 在pom.xml中导入swagger相关依赖

<!-- Swagger2是一款restful接口文档在线生成和在线接口调试工具 -->
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

        <!-- 引入UI包（美化swagger） -->
        <!-- https://mvnrepository.com/artifact/com.github.xiaoymin/swagger-bootstrap-ui -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.3</version>
        </dependency>

注：其中swagger-bootstrap-ui依赖不是必须，这个是用来增强swagger的，用于美化接口文档页面风格。
（如果需要这个美化，则需要在以下Swagger2Config配置文件中加@EnableSwaggerBootstrapUI开启注解）
这里顺便贴一下两种页面风格。

没有引入美化依赖的风格，其访问地址（http://127.0.0.1:1221/swagger-ui.html#/）如下图：

引入美化工具依赖的风格，其访问地址（http://127.0.0.1:1221/doc.html）如下图：

2. 添加Swagger2Config配置文件

import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
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;

import java.util.ArrayList;
import java.util.List;

/**
 * Swagger2Config 接口文档配置文件
 * @author zhang
 * @date 2020-05-08 13:40:50
 */
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI // 引入美化swagger工具（增强功能）swagger-bootstrap-ui，需要开启@EnableSwaggerBootstrapUI注解
public class Swagger2Config {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 采用指定扫描的包路径来定义指定要建立API的目录。
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zhang.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://127.0.0.1:1221/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("demo系统")
                .description("一个自测demo，集成各种技术")
                .termsOfServiceUrl("http://127.0.0.1:1221/swagger-ui.html  美化swagger之后地址： http://127.0.0.1:1221/doc.html")
                .contact(new Contact("zhang", "https://github.com/zhang20200320/CommonRepository/tree/master/demo", "18292000084.163.com"))
                .version("1.0")
                .build();
    }

    private List<ApiKey> securitySchemes() {
        //设置请求头信息
        List<ApiKey> result = new ArrayList<>();
        ApiKey apiKey = new ApiKey("Authorization", "Authorization", "header");
        result.add(apiKey);
        return result;
    }
}

3. 在Controller中加入swagger注解

import com.zhang.demo.common.Annotation.NoRepeatSubmit;
import com.zhang.demo.common.CommonResult;
import com.zhang.demo.common.utils.Constant;
import com.zhang.demo.common.utils.QRCode.QRCodeUtil;
import com.zhang.demo.common.utils.RedisUtils;
import com.zhang.demo.common.utils.VerifyUtils;
import com.zhang.demo.entity.ZUserEntity;
import com.zhang.demo.form.ZCaptchaForm;
import com.zhang.demo.form.ZUserForm;
import com.zhang.demo.service.ZUserService;
import com.zhang.demo.vo.ZUserVo;
import io.swagger.annotations.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.util.StringUtils;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.Arrays;
import java.util.List;

/**
 * 用户
 * @author zhang
 * @date 2020-04-20 14:38:30
 */
@Api(tags = "用户管理", value= "用户管理", description = "用户接口") // 表示类的作用
//@ApiSort(value = 1)
@RestController
@RequestMapping("/user")
public class ZUserController {

    private static final Logger logger = LoggerFactory.getLogger(ZUserController.class);

    @Autowired
    private ZUserService zUserService;

    @Autowired
    private RedisUtils redisUtils;
    
	/**
     * 注册
     * 应用swagger
     *      @ApiOperationSort ———— 用于接口方法排序，使用该注解需要在swagger文档页面中文档管理中个性化设置中
     *                             勾选启动SwaggerBootstrapUi提供的增强功能，并保存。
     *      @ApiOperation ———— 表示方法说明
     * @param zUserForm
     * @return
     */
    @ApiOperationSort(3)
    @ApiOperation(value = "新增用户" ,  notes="新增注册") // 表示方法说明
    @NoRepeatSubmit(lockTime = 30)
    @PostMapping(value = "/register")
    public CommonResult<ZUserForm> register(@Validated(value = {ZUserForm.ZUserRegister.class}) @RequestBody ZUserForm zUserForm) {
        return CommonResult.success(zUserService.register(zUserForm));
    }

	/**
     * 用户信息
     * swagger2应用
     * @ApiImplicitParams : 用在方法上包含一组参数说明。
     * @ApiImplicitParam : 用来注解来给方法入参增加说明。
     *  参数：
     *    ·paramType：指定参数放在哪个地方
     *       ··header：请求参数放置于Request Header，使用@RequestHeader获取
     *       ··query：请求参数放置于请求地址，使用@RequestParam获取
     *       ··path：（用于restful接口）-->请求参数的获取：@PathVariable
     *       ··body：（不常用）
     *       ··form（不常用）
     *    ·name：参数名
     *    ·dataType：参数类型
     *    ·required：参数是否必须传(true | false)
     *    ·value：说明参数的意思
     *    ·defaultValue：参数的默认值
     *
     * @param userId 用户标识id
     * @return
     */
    @ApiOperationSort(4) // 用于接口方法排序
    @ApiOperation(value = "用户信息" ,  notes="获取指定用户详细信息")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query",name = "userId", value = "用户标识id", required = true, dataType = "String")
    })
    @GetMapping(value = "/zUserInfo")
    public CommonResult<ZUserVo> zUserInfo(@RequestParam(value = "userId", required = true) String userId) {
        return CommonResult.success(zUserService.queryZUserInfo(userId));
    }
    // 。。。。。。
}

4. 最后启动spring boot项目，浏览器访问http://127.0.0.1:1221/swagger-ui.html
   美化swagger之后地址： http://127.0.0.1:1221/doc.html

最后

到这里集成就已经结束了，，可以愉快的应用swagger文档啦。

附上源码，以便大家学习，这个demo将源源不断的新增各种技术，只是为了自测技术功能，便于后期学习掌握,欢迎大家一起来探索新知。
myGithub