SpringBoot集成Swagger2

官网：https://swagger.io/

一、快速开始

本文基于SpringBoot项目集成Swagger

①、建项目

②、相关依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>
<!-- 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

/**
 * @author PengHuAnZhi
 * @ProjectName SwaggerDemo
 * @Description TODO
 * @time 2021/9/27 14:30
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
}

④、Hello World请求

/**
 * @author PengHuAnZhi
 * @ProjectName SwaggerDemo
 * @Description TODO
 * @time 2021/9/27 14:27
 */
@RestController
public class HelloController {

    @RequestMapping(value = "/hello")
    public String helloWorld() {
        return "hello world";
    }
}

⑤、测试

启动项目访问http://localhost:8080/swagger-ui.html

从上到下依次是：Swagger信息，Controller接口信息，Models实体类信息

二、配置Swagger

①、配置Swagger基本信息

注入Swagger相关配置Bean ——docket

/**
 * @author PengHuAnZhi
 * @ProjectName SwaggerDemo
 * @Description TODO
 * @time 2021/9/27 14:30
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //配置文档信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("两米以下皆凡人", "https://blog.csdn.net/qq_43509535", "penghuanzhi@pwrd.com");
        return new ApiInfo(
                // 标题
                "彭焕智的Swagger2入门教程",
                // 描述
                "学习演示如何配置Swagger",
                // 版本
                "v1.0",
                // 组织链接
                "http://terms.service.url/组织链接",
                // 联系人信息
                contact,
                // 许可
                "Apatch 2.0 许可",
                // 许可连接
                "许可链接",
                // 扩展
                new ArrayList<>()
        );
    }
}

测试

②、配置Swagger扫描位置

从上图可以发现，在不配置扫描位置的情况下，默认会把error请求也给显示出来了，Models中还会把ModelAndView和View两个实体Bean也给加载出来，这对于我们来说是不需要的，所以可以配置扫描位置将其过滤出来

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
        //默认开启，如果不需要Swagger接口文档，就传入false
        .enable(true)
        .apiInfo(apiInfo())
        // 通过select()方法，去配置扫描接口
        .select()
        // RequestHandlerSelectors配置如何扫描接口
        // basePackage:指定要扫描的包
        // any():扫描全部
        // none():不扫描
        // withClassAnnotation:扫描类上的注解，参数是一个注解的反射对象，比如：RestController.class
        // withMethodAnnotation:扫描方法上的注解，比如：GetMapping.class
        .apis(RequestHandlerSelectors.basePackage("com.phz.swagger.controller"))
        // 配置如何通过path过滤,即这里只扫描请求以hello开头的请求，比如hello/world
        .paths(PathSelectors.ant("/hello/**"))
        .build();
}

小问题

• 现在我们希望只在开发环境开启Swagger，发布的时候就不开启了，那也就是说enable方法传入的值是一个动态的才行，可以这样修改代码

public Docket docket(Environment environment) {
    boolean b = environment.acceptsProfiles(Profiles.of("dev", "test"));
    return new Docket(DocumentationType.SWAGGER_2)
            //默认开启，如果不需要Swagger接口文档，就传入false
            .enable(b)

③、配置Swagger分组

此配置可以很好的区分不同的人开发的不同模块，每一个Docket里面扫描各自相对应的包即可

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

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

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

@Bean
public Docket docket(Environment environment) {
    boolean b = environment.acceptsProfiles(Profiles.of("dev", "test"));
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("group")
            //默认开启，如果不需要Swagger接口文档，就传入false
            .enable(b)
            .apiInfo(apiInfo())
            // 通过select()方法，去配置扫描接口
            .select()
            // RequestHandlerSelectors配置如何扫描接口
            // basePackage:指定要扫描的包
            // any():扫描全部
            // none():不扫描
            // withClassAnnotation:扫描类上的注解，参数是一个注解的反射对象，比如：RestController.class
            // withMethodAnnotation:扫描方法上的注解，比如：GetMapping.class
            .apis(RequestHandlerSelectors.basePackage("com.phz.swagger.controller"))
            // 配置如何通过path过滤,即这里只扫描请求以hello开头的请求，比如hello/world
            .paths(PathSelectors.ant("/hello/**"))
            .build();
}

//配置文档信息
private ApiInfo apiInfo() {
    Contact contact = new Contact("两米以下皆凡人", "https://blog.csdn.net/qq_43509535", "penghuanzhi@pwrd.com");
    return new ApiInfo(
            // 标题
            "彭焕智的Swagger2入门教程",
            // 描述
            "学习演示如何配置Swagger",
            // 版本
            "v1.0",
            // 组织链接
            "http://terms.service.url/组织链接",
            // 联系人信息
            contact,
            // 许可
            "Apatch 2.0 许可",
            // 许可连接
            "许可链接",
            // 扩展
            new ArrayList<>()
    );
}

④、配置Swagger实体类

只要接口中，返回值中存在实体类，它就会被扫描到Swagger中

/**
 * @author PengHuAnZhi
 * @ProjectName SwaggerDemo
 * @Description TODO
 * @time 2021/9/27 17:02
 */
public class User {
    private String name;
    private String password;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

@PostMapping(value = "/user")
public User user(){
    return new User();
}

这样配置也可以，但是一个model复杂了以后，就看着比较麻烦了，所以还可以进一步配置，给model以及model各个属性加上描述

/**
 * @author PengHuAnZhi
 * @ProjectName SwaggerDemo
 * @Description TODO
 * @time 2021/9/27 17:02
 */
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    private String name;
    @ApiModelProperty("密码")
    private String password;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

⑤、配置Controller控制器

给Controller加上描述

@Api(tags = "hello控制器")
@RestController
public class HelloController {

⑥、配置请求

@ApiOperation("Hello请求")
@GetMapping(value = "/hello")
public String helloWorld() {
    return "hello world";
}

⑦、配置参数

@ApiOperation("登录请求")
@PostMapping(value = "/login")
public void login(@ApiParam("用户名") String username, @ApiParam("密码") String password) {
    System.out.println("登录成功");
}