【Springboot】整合Swagger（配置swagger信息、分组、接口扫描、实体类、控制器备注）

一、基本配置

1.1 依赖

找一个之前的Springboot项目，为其添加依赖。

链接：https://mvnrepository.com/search?q=springfox+swagger

<!-- 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>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-common -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

1.2 配置类

启动Swagger2

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

@Configuration
@EnableSwagger2
public class SwaggerConfig {
}

1.3 启动

启动项目后，打开浏览器：http://localhost:8080/swagger-ui.html

可查看到如下界面

1. Swagger信息
2. 接口信息
3. 实体类信息
4. 组

二、配置

2.1 配置Swagger信息

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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
public class SwaggerConfig {
    // 配置Swagger的Docket实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    // 配置Swagger信息——ApiInfo
    private ApiInfo apiInfo() {
        // 作者信息
        Contact contact = new Contact("小明","url","xiaoming@qq.com");
        return new ApiInfo(
                "小明的Swagger",
                "这里是描述文档",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

2.2 配置接口信息

接着上面的配置，继续修改。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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
public class SwaggerConfig {
    // 配置Swagger的Docket实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(true)   // false 关闭swagger; true 启动swagger
                .select()
                // RequestHandlerSelectors 配置要扫描接口的方式
                // basePackage() 指定要扫描的包
                // any() 扫描全部
                // none() 不扫描
                // withClassAnnotation() 扫描类上的注解  .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                // withMethodAnnotation() 扫描方法上的注解  .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
                .apis(RequestHandlerSelectors.basePackage("com.zqc.personmanagement.Controller"))
                .paths(PathSelectors.ant("/Controller"))  // 过滤路径
                .build();
    }

    // 配置Swagger信息——ApiInfo
    private ApiInfo apiInfo() {
        // 作者信息
        Contact contact = new Contact("小明","url","xiaoming@qq.com");
        return new ApiInfo(
                "小明的Swagger",
                "这里是描述文档",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

2.3 配置API文档分组

@Bean
public Docket docket1() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}

代码如下：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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
public class SwaggerConfig {
    // 配置Swagger的Docket实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("新分组")
                .enable(true)   // false 关闭swagger; true 启动swagger
                .select()
                // RequestHandlerSelectors 配置要扫描接口的方式
                // basePackage() 指定要扫描的包
                // any() 扫描全部
                // none() 不扫描
                // withClassAnnotation() 扫描类上的注解  .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                // withMethodAnnotation() 扫描方法上的注解  .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
                .apis(RequestHandlerSelectors.basePackage("com.zqc.personmanagement.Controller"))
                .paths(PathSelectors.ant("/Controller"))  // 过滤路径
                .build();
    }

    // 配置Swagger信息——ApiInfo
    private ApiInfo apiInfo() {
        // 作者信息
        Contact contact = new Contact("小明","url","xiaoming@qq.com");
        return new ApiInfo(
                "小明的Swagger",
                "这里是描述文档",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

    @Bean
    public Docket docket1() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }

    @Bean
    public Docket docket2() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }
}

后面再配置docket1和docket2就可以有多个分组了。

2.4 实体类、控制器备注

创建一个实体类 ，如下：

src/main/java/com/zqc/personmanagement/pojo/User.java

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户名")
    public String username;

    @ApiModelProperty("密码")
    public String password;
}

添加一个控制器，如下：
src/main/java/com/zqc/personmanagement/Controller/SwaggerController.java

import com.zqc.personmanagement.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class SwaggerController {

    @ApiOperation("User的控制类")
    // 只要接口中，返回值中存在实体类，就会被扫描到Swagger内
    @PostMapping(value = "/user")
    public User user(@ApiParam("用户名") String name) {
        return new User();
    }
}

此时运行Swagger-UI可查看到其中的模型：

@ApiModel("用户实体类")：作用于类的注释，将显示的类名转换为备注。

@ApiModelProperty("用户名")：作用域属性，为属性添加备注。

@ApiOperation("User的控制类")：为控制器添加备注。

@ApiParam("用户名")：为方法中的属性添加备注。

参考：https://www.bilibili.com/video/BV1PE411i7CV?p=50