Swagger学习记录

视频地址： 【狂神说Java】一小时掌握Swagger技术_哔哩哔哩_bilibili笔记资料交流都在我们的平台：www.kuangstudy.com秦疆老师SpringBoot课程扩展之Swagger学习；这可能是全网最详细的Swagger视频了从生活到代码，从简单到深入。风趣幽默,通俗易懂。狂神说Java交流群：664386224https://www.bilibili.com/video/BV1Y441197Lw?spm_id_from=333.999.0.0

参考代码已上传至gitee： Swagger: Swagger就是一款能更好的书写API文档的框架

SpringBoot+Vue是当前比较主流的前后端分离技术栈。

前端 -> 前端控制层、视图层
后端 -> 后端控制层、服务层、数据访问层
前后端通过API进行交互
前后端相对独立且松耦合，前后端甚至可以部署在不同的服务器上。

那么前后端分离会产生什么样的一些问题呢？

前后端集成联调，前端或后端人员无法做到"及时协商，尽早解决"，最终导致问题集中爆发。

如何解决这个问题呢？

定义schema [ 计划的提纲 ]，并实时跟踪最新的API，降低集成风险。

什么是swagger？它能给我们带来什么样的好处呢？

任何一门技术的出现都有它存在的原因，Swagger也一样。我们知道随着互联网技术的不断迭代更新，现在的系统架构基本都变成了前后端分离的形态， 前端和后端的唯一联系，变成了API接口,API文档变成了前后端开发人员联系的纽带，变得越来越重要。**Swagger就是一款能更好的书写API文档的框架。**下面我们就来学习一下Swagger的具体用法。

总结：Swagger就是一个用来定义接口标准，接口规范，同时能根据你的代码自动生成接口说明文档的一个工具。

Swagger简介

号称世界上最流行的API框架
直接运行，在线测试API
支持多种语言（如：Java，PHP等）
官网：https://swagger.io/

SpringBoot集成Swagger

1、新建一个Spring Boot项目

2、导入相关依赖，此处一定要注意和boot版本对应，有时还会报错。

<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>

3、编写HelloController，测试确保运行成功！

@RestController
public class Hello {
    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }
}

4、编写Swagger配置类对Swagger进行配置

Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。
通过apiInfo()属性配置文档信息
Docket 实例关联上 apiInfo()

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        //配置了Swagger的Docket容器的Bean实例
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }
    //配置Swagger
    private ApiInfo apiInfo(){
        //开发文档的联系人信息
        Contact contact = new Contact("zlk", "https://blog.csdn.net/friggly?spm=1000.2115.3001.5343", "zlk@163.com");
        //配置Swagger信息
        return new ApiInfo(
                "SpringBoot整合Swagger使用",
                "SpringBoot整合Swagger,详细信息...",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                 new ArrayList());
    }
}

5、访问测试：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；

Swagger配置接口扫描

1、构建Docket时通过select()方法配置如何去扫描接口：

2、接口扫描策略：

（1）扫描所有接口

RequestHandlerSelectors.any()

（2）不扫描接口

RequestHandlerSelectors.none()

（3）扫描指定包

RequestHandlerSelectors.basePackage("com.zlk.controller")

（4）基于类的扫描：

例如：基于类上面@RestController注解的扫描

RequestHandlerSelectors.withClassAnnotation(RestController.class)

（5）基于方法上的注解扫描（下述例子中只扫描get请求）

RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)

除此之外，我们还可以配置接口扫描过滤：
    any() // 任何请求都扫描
    none() // 任何请求都不扫描
    regex(final String pathRegex) // 通过正则表达式控制
    ant(final String antPattern) // 通过ant()控制

    @Bean
    public Docket docket() {
        //配置了Swagger的Docket容器的Bean实例
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zlk.controller"))
                // 配置如何通过path过滤,即这里只扫描请求以/zlk开头的接口
                .paths(PathSelectors.ant("/zlk/**"))
                .build();
    }

配置Swagger开关

1、通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问。

.enable(true)   //swagger展示
.enable(false)  //配置是否启用Swagger，如果是false，在浏览器将无法访问

2、如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示呢？

#激活dev环境
spring.profiles.active=dev

判断是不是生产环境
注入enable（flag）

    @Bean
    public Docket docket(Environment environment) {

        // 设置要显示swagger的环境
        Profiles of = Profiles.of("dev", "test");
        // 判断当前是否处于该环境
        // 通过 enable() 接收此参数判断是否要显示
        boolean b = environment.acceptsProfiles(of);

        //配置了Swagger的Docket容器的Bean实例
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(b)//配置是否启用Swagger，如果是false，在浏览器将无法访问
                //通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zlk.controller"))
                // 配置如何通过path过滤,即这里只扫描请求以/zlk开头的接口
                .paths(PathSelectors.ant("/zlk/**"))
                .build();
    }

配置API文档的分组

1、如果没有配置分组，默认是default。通过groupName()方法即可配置分组：

@Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("星悦糖") // 配置分组
       // 省略配置....
}

2、如何配置多个分组？配置多个分组只需要配置多个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");
}

实体类配置

1、新建一个实体类

@ApiModel("用户实体")
public class User {
   @ApiModelProperty("用户名")
   public String username;
   @ApiModelProperty("密码")
   public String password;
}

2、只要这个实体在请求接口的返回值上（即使是泛型），他就会被扫描到Swagger中：

@RequestMapping("/getUser")
public User getUser(){
   return new User();
}

3、运行结果

注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。

@ApiModel为类添加注释

@ApiModelProperty为类属性添加注释

常用注解

Swagger注解	简单说明
@Api(tags = "xxx模块说明")	作用在模块类上,
@ApiOperation("xxx接口说明")	作用在接口方法上
@ApiModel("xxxPOJO说明")	作用在模型类上：如VO、BO
@ApiModelProperty(value = "xxx",hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam("xxx参数说明")	作用在参数、方法和字段上，类似@ApiModelProperty

我们也可以给请求的接口配置一些注释，这样的话，可以给一些比较难理解的属性或者接口，增加一些配置信息，让人更容易阅读！

@Api

作用：作用在类上用来指定接口的描述文字。

语法：@Api(tags = "xxxxxxxxxxxx")

@RestController
@Api(tags = "MongoDB相关接口描述")
public class MongoDBController {
    @Autowired
    private  MongoTemplate mongoTemplate;

}

运行结果：

@ApiOperation

作用：作用在方法上用来对接口中具体的方法做描述

语法：@ApiOperation(value = "创建集合",notes = "创建集合详细描述")

    @GetMapping("/hello2")
    @ApiOperation(value = "hello接口",notes = "hello接口详细描述")
    public String hello2( String username){
        return "hello"+username;
    }

运行结果：

@ApiImplicitParams

作用：作用在方法上用来对接口中的参数进行说明

通过form表单方式传参

    @GetMapping("/hello3")
    @ApiOperation(value = "hello3接口",notes = "hello3接口详细描述")
    @ApiImplicitParams({
            @ApiImplicitParam(name="username",value = "用户名"),
            @ApiImplicitParam(name="password",value="密码")
    })
    public String hello3(String userName,String password){
        return "hello"+userName+"\t"+password;
    }

通过地址栏方式传参

    @GetMapping("/hello4/{username}/{password}")
    @ApiOperation(value = "hello4接口",notes = "hello4接口详细描述")
    @ApiImplicitParams({
            @ApiImplicitParam(name="username",value = "用户名",paramType ="path"),
            @ApiImplicitParam(name="password",value="密码",paramType = "path")
    })
    public String hello4(@PathVariable("username") String username, @PathVariable("password") String password){
        return "hello"+username+"\t"+password;
    }

通过json格式传参

注意：此处传递的是某个属性参数时，如果在类上添加了@RestController注解，那么@RequestBody注解可以省略。如果类上添加的是@Controller注解，那么则需要在方法的参数中添加@RequestBody注解

    @GetMapping("/hello5")
    @ApiOperation(value = "hello5接口",notes = "hello5接口详细描述")
    @ApiImplicitParams({
            @ApiImplicitParam(name="username",value = "用户名",paramType = "body"),
            @ApiImplicitParam(name="password",value="密码",paramType = "body")
    })
    public String hello5(@RequestBody String username, @RequestBody String password){
        return "hello"+username+"\t"+password;
    }

通过json格式对象传参

    @GetMapping("/hello6")
    @ApiOperation(value = "hello接口",notes = "hello接口详细描述")
    public void hello6(@RequestBody User user){
        System.out.println("通过json格式对象传参");
    }

@ApiParam("用户名")

    @ApiOperation("hello接口")
    @GetMapping("/hello2")
    public String hello2(@ApiParam("用户名") String username){
        return "hello"+username;
    }

拓展：其他皮肤

我们可以导入不同的包实现不同的皮肤定义：

1、默认的 访问 http://localhost:8080/swagger-ui.html

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

2、bootstrap-ui 访问 http://localhost:8080/doc.html

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

3、Layui-ui 访问 http://localhost:8080/docs.html

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
   <groupId>com.github.caspar-chen</groupId>
   <artifactId>swagger-ui-layer</artifactId>
   <version>1.1.3</version>
</dependency>

4、mg-ui 访问 http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
   <groupId>com.zyplayer</groupId>
   <artifactId>swagger-mg-ui</artifactId>
   <version>1.0.6</version>
</dependency>

原文链接: https://blog.csdn.net/friggly/article/details/124499668