springboot 集成 Swagger

优点：
（1）aio文档与api定义同步更新
（2）直接运行，可在线测试
（3）支持多种语言
 

maven下载依赖

Swagger2是新版的。

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

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

配置Swagger

config ->SwaggerConfig.java

package com.lxc.sprint_boot_01.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
}

访问Swagger：

​​http://localhost:9001/swagger-ui.html#/​​

配置Swagger

Swagger的bean实例 Docket，

package com.lxc.sprint_boot_01.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Component;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2 // 开启swagger
public class SwaggerConfig {

    // 注册bean
    @Bean
    public Docket docket () {
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        // 配置swagger信息
        docket.apiInfo(apiInfo());
        return docket;
    }
    public static ApiInfo apiInfo() {
        // 作者信息
        Contact concat = new Contact("吕星辰", "无", "1063614453@qq.com");
        // 文档头部信息
        return new ApiInfo(
                "测试接口文档",
                "没啥好说的。",
                "1.0.0",
                "暂时没有。",
                concat,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

配置Swagger，扫描接口

扫描接口的方式：RequestHandlerSelectors —— 配置扫描接口的方式

（1）RequestHandlerSelectors.basePackage()
指定扫描包

（2）RequestHandlerSelectors.any()
扫描全部

（3）RequestHandlerSelectors.none()
不扫描
（4）RequestHandlerSelectors.withMethodAnnotation(RestController.class)
只会去扫描 类上有 @RestController注解的类 。

（5）RequestHandlerSelectors.withClassAnnotation(GetMapping.class)
只会扫描方法上有 @GetMapping 注解的方法

下边是以包的方式去扫描：

// 注册bean
@Bean
public Docket docket () {
    Docket docket = new Docket(DocumentationType.SWAGGER_2);
    // 配置swagger信息
    docket
            .apiInfo(apiInfo()) // 配置文档的头部信息及作者信息
            .select()
            // api接口配置:RequestHandlerSelectors配置扫描接口的方式 - 以包的形式
            .apis(RequestHandlerSelectors.basePackage("com.lxc.sprint_boot_01.controller"))
            .build();
    return docket;
}

也可以指定扫描哪一个路径下的接口

.paths(PathSelectors.ant("/**"))

@Bean
public Docket docket () {
    Docket docket = new Docket(DocumentationType.SWAGGER_2);
    // 配置swagger信息
    docket
            .apiInfo(apiInfo()) // 配置文档的头部信息及作者信息
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.lxc.sprint_boot_01.controller"))
            // 指定扫描接口以 /map/开头的所有接口
            .paths(PathSelectors.ant("/map/**"))
            .build();
    return docket;
}

是否自动启动

enable() 是否启动swagger，为false不会启动swagger, true会启动swagger

// 注册bean
@Bean
public Docket docket () {
    Docket docket = new Docket(DocumentationType.SWAGGER_2);
    // 配置swagger信息
    docket
            .apiInfo(apiInfo())
            .enable(true)
    return docket;
}

如何设置Swapper只在开发环境使用，生产环境取消？

第一步：
首先要配置多环境，具体的规则，之前文章有记录：

第二步：
通过参数，environment.acceptsProfiles(profiles) 监听目前的环境是否是我们设定的环境。

// 注册bean
@Bean
public Docket docket (Environment environment) {
     // 方法一：直接获取properties里边的属性,然后把 "true" 转化为 true
     // 方法一必须在application-dev.properties中自定义属性 swagger=true，在生产环境
     // application-product.properties中自定义属性 swagger=false 
     boolean isEnableSwaggerPro = Boolean.parseBoolean(environment.getProperty("swagger"));

    // 方法二：   
    // 设置要显示的Swapper的环境 - 下边设定的 只有开发环境和测试环境开启 Swagger
    Profiles profiles = Profiles.of("dev", "test");
    // 通过environment.acceptsProfiles 判断是否处在自己设定的环境当中
    boolean isEnableSwagger = environment.acceptsProfiles(profiles);
    Docket docket = new Docket(DocumentationType.SWAGGER_2);
    // 配置swagger信息
    docket
            .apiInfo(apiInfo()) // 配置文档的头部信息及作者信息
            .enable(isEnableSwagger)
    return docket;
}

分组

上边的分组什么意思呢？

在swagger中可以配置这个分组，当多人开发一个项目时，大家写的接口肯定不一样，所以，为了方便管理，我们可以给接口分组，看下配置就明白了。

可以配置多个Bean来实现多个分组：
 

@Configuration
@EnableSwagger2 // 开启swagger
public class SwaggerConfig {
    // 可注册配置多个 bean 
    @Bean
    public Docket docketOne () {
        return new Docket(DocumentationType.SWAGGER_2).groupName("大胖儿-写的接口");
    }
    @Bean
    public Docket docketTwo () {
        return new Docket(DocumentationType.SWAGGER_2).groupName("小K-写的接口");
    }
    @Bean
    public Docket docket (Environment environment) {
        boolean isEnableSwaggerPro = Boolean.parseBoolean(environment.getProperty("swagger"));
        docket
                .apiInfo(apiInfo()) // 配置文档的头部信息及作者信息
                .groupName("吕星辰-写的接口")
                .enable(isEnableSwagger).select().apis(RequestHandlerSelectors.basePackage("com.lxc.sprint_boot_01.controller"))
                .paths(PathSelectors.ant("/**"))
                .build();
        return docket;
    }
    public static ApiInfo apiInfo() {
        // 作者信息
        Contact concat = new Contact("吕星辰", "无", "1063614453@qq.com");
        // 文档头部信息
        return new ApiInfo(
                "测试接口文档",
                "没啥好说的。",
                "1.0.0",
                "暂时没有。",
                concat,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

再来看下页面效果：

Model模型

页面中，可以把model模型（实体类）显示出来，并添加注释。

但是需要注意的是，controller 层方法必须要返回实体类

@GetMapping(value = "/test")
public List<User> userTest(Model model) {
   return userService.getTest();
}

在实体类型，添加注解

@ApiModel 类的文档注释

@ApiModelProperty  字段注释

来对字段进行详情说明：

// ···
@ApiModel(value = "user模型字段")
public class User extends PageNation{
    @ApiModelProperty(value = "id字段")
    @NotNull(message = "id 不能为空", groups = {GroupAInterface.class})
    private Integer id;
    @ApiModelProperty(value = "name字段")
    @NotNull(message = "name不能为空", groups = {GroupAInterface.class, GroupBInterface.class})
    public String name;
    // ···
}

在controller方法上添加注解

// 查询全部(没有分页的)
@ApiOperation(value = "查询全部(没有分页的)")
@GetMapping(value = "/getAll")
public ComResponse getAll() {
    return userService.getAllService();
}

// 根据条件查询
@ApiOperation(value = "根据条件查询")
@GetMapping(value = "/getCondition")
public ComResponse getCondition(@RequestBody  Map<String, Object> map) {
    System.out.println(JSON.toJSONString(map));
    return userService.getConditionService(map);
}

看下效果：

在controller类上添加注解

@Api(tags = {"用户接口"}, description = "这只是一个描述！")

tags属性值是一个数组，开发中肯定有多个controller，通过tags来区别controller的用途；

description 属性已经过时，但是也能用，用来描述controller的。

@Api(tags = {"用户接口", "订单接口"}, description = "这只是一个描述！")
@RestController
public class TestController {
    // ··· ···
}

补充：

Swagger集成给第三方UI

<!--Swagger配置-->
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!--第三方的ui界面-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

Swagger模块化，如果Swagger在别的模块，如何引入主模块呢？？？

实际项目中，我会把Swagger这种辅助模块，抽离出来，通常放到common模块下的子模块中，下边我的子模块是service_base模块，主模块为service模块下的service_edu模块，common与service模块同级。

第一步：

在common模块中引入swagger依赖及第三方ui， 在common的子模块service_base模块中配置Swagger

第二步：

配置完之后，在service模块中引入 自定义模块 service_base模块

 第三步：

引入完之后，在主模块中还是用不了Service_base模块下的Swagger，此时，需要在主模块的启动类上添加 一个模块扫描：

启动时扫描 com.lxc包下的所有包

 第四步：

启动访问 ​​http://localhost:你配置的端口号/doc.html​​