【Spring Boot】Swagger集成springboot

---

一、环境配置

1. 配置springboot-web项目，参考文章：【Spring Boot】快速上手SpringBoot
2. 导入swagger相关依赖：

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

3. 配置swaggerconfig类：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
}

4. 启动项目，并访问：http://localhost:8080/swagger-ui/index.html
   

二、Swagger的使用

1.了解Swagger

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

作用：

1. 接口的文档在线自动生成。
2. 功能测试。

2.配置Swagger信息

ApiInfo类部分源代码：与我们没有配置时，访问初始界面的信息是一直的，我们可以自己写一个ApiInfo类覆盖它，来修改swagger-ui/index.html页面的信息。

new ApiInfo("Api Documentation", 
"Api Documentation", 
"1.0", "urn:tos",
 DEFAULT_CONTACT,
  "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", 
  new ArrayList());

SwaggerConfig.java配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()) ;
    }

    //配置Swagger信息
    private ApiInfo apiInfo(){

        //作者信息
        Contact contact = new Contact("高朗", "https://blog.csdn.net/qq_43466788", "3211384971@qq.com");

        return new ApiInfo("项目API文档",
                "API文档",
                "1.0",
                "https://blog.csdn.net/qq_43466788",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }


}

3. Swagger配置扫描接口和过滤

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //扫描controller包下接口
                .apis(RequestHandlerSelectors.basePackage("com.gaolang.controller"))
                //paths():过滤掉什么路径，这里过滤掉了gaolang包下的所有
                .paths(PathSelectors.ant("/gaolang/**"))
                .build()
                ;
    }

    //配置Swagger信息
    private ApiInfo apiInfo(){

        //作者信息
        Contact contact = new Contact("高朗", "https://blog.csdn.net/qq_43466788", "3211384971@qq.com");

        return new ApiInfo("项目API文档",
                "API文档",
                "1.0",
                "https://blog.csdn.net/qq_43466788",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

    
}

4.配置是否启动Swagger

我们可以看到Docket对象中，默认是true，是开启的：

我们要关闭Swagger的话只需设置enable为false即可：

5.Swagger API注释

1. 实体类的注释：

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

    @ApiModelProperty("用户名")
    public String name;
    @ApiModelProperty("密码")
    public String password;
}

2.controller类及方法注释

@Api(value = "测试Controller",tags = {"测试接口"})
@RestController
public class TestController {

    @ApiOperation(value = "测试",tags = {"测试copy"},notes = "注意点")
    @RequestMapping("/test")
    public String test(){
        return "Hello";
    }

3. 方法中字段名可以用@ApiParam(“用户名”)注解

6.Swagger分组测试

就是.groupName("XXX")的使用

分组A、B、C等，每组扫描不同的包下API，分门别类管理：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("A")
                .select()
                .apis(RequestHandlerSelectors.basePackage("包A下api"))
                .build()
                ;
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("B")
                .select()
                .apis(RequestHandlerSelectors.basePackage("包B下api"))
                .build()
                ;
    }


    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("C")
                .select()
                .apis(RequestHandlerSelectors.basePackage("包C下api"))
                .build()
                ;
    }
}

7.测试API

1. 选择一个API进行测试==》Try it out

2. 填写参数，然后提交

3. 我们就可以看到测试信息，200表示没有出现错误