SpringBoot学习(二):Swagger文档集成

1.什么是Swagger?

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。总体目标是使客户端和文件系统作为服务器，以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码中，允许API始终保持同步。Swagger让部署管理和使用功能强大的API从未如此简单。

2. 集成原生配置Swagger

2.1 添加依赖

在pom.xml文件中引入下面依赖

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>

<dependency>
	<groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
 	<version>2.9.2</version>
</dependency>

2.2 添加Swagger配置类

package com.hui.javalearn.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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author liuqh
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
             .apiInfo(apiInfo())
             .select()
             //swagger 文档扫码的包,也就是控制所在包
             .apis(RequestHandlerSelectors.basePackage("com.hui.javalearn.controller"))
             .paths(PathSelectors.any())
             .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("接口列表1.1")
                .description("Swagger2 接口文档")
                .termsOfServiceUrl("http://liuqh.icu/")
                .version("1.0")
                .build();
    }
}

从这里可以看出Swagger的一个缺点：无法通过SpringBoot的配置文件进行配置，所以配置并不能灵活转变spring4all社区出品的swagger-spring-boot-starter可以解决这个问题。

2.3 添加controller

package com.hui.javalearn.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.ArrayList;

/**
 * @author liuqh
 */
@Api(tags = "Swagger文档测试使用")
@RestController
@RequestMapping("/doc")
public class DocController {
    /**
     * 测试文档有一个参数情况
     * @param desc
     * @return
     */
    @ApiOperation(value = "文档说明", notes = "有一个参数的情况")
    @ApiImplicitParam(name = "desc", value = "说明", required = true, paramType = "query", dataType = "String")
    @GetMapping("/desc")
    public ArrayList<String> index(@RequestParam(value = "desc") String desc) {
        ArrayList<String> resultMapList = new ArrayList<>();
        resultMapList.add("文档说明");
        resultMapList.add(desc);
        return resultMapList;
    }

    /**
     * 测试文档有多个参数
     * @param version
     * @param token
     * @return
     */
    @ApiOperation(value = "文档版本", notes = "有多个参数的情况")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "version", value = "版本号", required = true, paramType = "query", dataType = "String"),
            @ApiImplicitParam(name = "token", value = "令牌", required = true, paramType = "query", dataType = "String")

    })
    @GetMapping("/version")
    public ArrayList<String> version(@RequestParam(value = "version") String version, @RequestParam(value = "token") String token) {
        ArrayList<String> resultMapList = new ArrayList<>();
        resultMapList.add("版本:" + version);
        resultMapList.add("令牌:" +token );
        return resultMapList;
    }
}

2.4 启动验证

访问地址: http://127.0.0.1:8080/swagger-ui.html

3. 集成 SwaggerBootstrapUi

注意: 为了区分原生配置Swagger,建议删除原来的一些操作

3.1 添加依赖

<!--SwaggerBootstrapUi依赖 开始部分 -->
<!--文档: https://www.bookstack.cn/read/swagger-bootstrap-ui/3.md -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>
<!--SwaggerBootstrapUi依赖 结束部分 -->

3.2 添加Swagger配置类

package com.hui.javalearn.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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerBootstrapUiConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //swagger 文档扫码的包,也就是控制所在包
                .apis(RequestHandlerSelectors.basePackage("com.hui.javalearn"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger-bootstrap-ui 文档使用")
                .description("集成swagger-bootstrap-ui到SpringBoot")
                .termsOfServiceUrl("http://localhost:8999/")
                .contact("刘庆辉")
                .version("1.0")
                .build();
    }
}

3.3 添加controller

package com.hui.javalearn.controller;

import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;

/**
 * @author liuqh
 */
@Api(tags = "Swagger文档测试使用")
@RestController
@RequestMapping("/doc")
public class DocController {
    /**
     *
     * @param desc
     * @return
     */
    @ApiOperation(value = "说明-模拟一个参数的情况", notes = "有一个参数的情况")
    @PostMapping("/desc")
    public ArrayList<String> index(@ApiParam("说明") @RequestParam(value = "desc") String desc) {
        ArrayList<String> resultMapList = new ArrayList<>();
        resultMapList.add("文档说明");
        resultMapList.add(desc);
        return resultMapList;
    }

    /**
     * 测试文档有多个参数
     * @param version
     * @param token
     * @return
     */
    @ApiOperation(value = "版本-模拟多个参数的情况", notes = "有多个参数的情况")
    @PostMapping("/version")
    public ArrayList<String> version(@ApiParam("版本")@RequestParam(value = "version") String version,
                                     @ApiParam(value = "令牌",required = true) @RequestParam(value = "token") String token
    ) {
        ArrayList<String> resultMapList = new ArrayList<>();
        resultMapList.add("版本:" + version);
        resultMapList.add("令牌:" +token );
        return resultMapList;
    }
}

3.4 启动验证

访问地址: http://127.0.0.1:8080/doc.html

swagger-bootstrap-ui 指南

源码地址

3.5 设置登录权限

1.修改application.yml

## 开启Swagger的Basic认证功能,默认是false
swagger:
  basic:
    enable:  true
    username: admin
    password: 123456

2.修改配置类SwaggerBootstrapUiConfig

@Configuration
@EnableSwagger2
// 添加增强注解
@EnableSwaggerBootstrapUI
public class SwaggerBootstrapUiConfig {
  ...
}

3.访问效果

4.文档

swagger-bootstrap-ui文档