Swagger学习记录

阳光穿透心脏的1/2处 2023-09-29 12:38 14阅读 0赞

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

**参考代码已上传至gitee：**[Swagger: Swagger就是一款能更好的书写API文档的框架][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的界面；

![fcb3007ee3014f439cde7b9a3e1a52cf.png][]

# 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文档的分组 #

![e1de797061fc4ac28e4c965bff84afb1.png][] 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、运行结果

![d48ccc3dfe0f4639992d554f049e4b39.png][]

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

@ApiModel为类添加注释

@ApiModelProperty为类属性添加注释

# 常用注解 #

<table> 
 <thead> 
  <tr> 
   <th style="width:317px;">Swagger注解</th> 
   <th style="width:531px;">简单说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td style="width:317px;">@Api(tags = "xxx模块说明")</td> 
   <td style="width:531px;">作用在模块类上,</td> 
  </tr> 
  <tr> 
   <td style="width:317px;">@ApiOperation("xxx接口说明")</td> 
   <td style="width:531px;">作用在接口方法上</td> 
  </tr> 
  <tr> 
   <td style="width:317px;">@ApiModel("xxxPOJO说明")</td> 
   <td style="width:531px;">作用在模型类上：如VO、BO</td> 
  </tr> 
  <tr> 
   <td style="width:317px;">@ApiModelProperty(value = "xxx",hidden = true)</td> 
   <td style="width:531px;">作用在类方法和属性上，hidden设置为true可以隐藏该属性</td> 
  </tr> 
  <tr> 
   <td style="width:317px;">@ApiParam("xxx参数说明")</td> 
   <td style="width:531px;">作用在参数、方法和字段上，类似@ApiModelProperty</td> 
  </tr> 
 </tbody> 
</table>

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

## @Api ##

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

语法：@Api(tags = “xxxxxxxxxxxx”)

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

运行结果：

![fa481f3c0054431189ee0820c0820b89.png][]

## @ApiOperation ##

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

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

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

运行结果：

![af32e54c8b6540f58f6d689bad41764f.png][]

## @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;
        }

![374fe001256342d895d3015153240c94.png][]

### 通过地址栏方式传参 ###

@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;
        }

![af71bc55b0d740e7b40951eeee441774.png][]

### 通过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;
        }

![9931f7c605dc4c1981e910f1fbd09782.png][]

### 通过json格式对象传参 ###

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

![b7dfb01ed1f44628a1d63472214266f8.png][]

![e4e299e64e80448fb7ae9bf6465674d6.png][]

### @ApiParam("用户名") ###

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

# ![f94d21cc9f9649748db1b74e5d9efb66.png][] #

# 拓展：其他皮肤 #

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

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

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

![51aa3d314b5114aee2f614c060c64e56.png][]

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

<dependency>
       <groupId>com.github.xiaoymin</groupId>
       <artifactId>swagger-bootstrap-ui</artifactId>
       <version>1.9.1</version>
    </dependency>

![cf1a1583f2437707149543e408ab385b.png][]

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

<dependency>
       <groupId>com.github.caspar-chen</groupId>
       <artifactId>swagger-ui-layer</artifactId>
       <version>1.1.3</version>
    </dependency>

![32805a6ad74bcd701162c78f8a5e66af.png][]

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

<dependency>
       <groupId>com.zyplayer</groupId>
       <artifactId>swagger-mg-ui</artifactId>
       <version>1.0.6</version>
    </dependency>

![1dcc7a7ecfebe222c3c74a1967917804.png][]

[33512603f27829b1279b59de5c725510973b17cf.jpg_57w_57h_1c.png]: http://i0.hdslb.com/bfs/archive/33512603f27829b1279b59de5c725510973b17cf.jpg@57w_57h_1c.png
[Java_Swagger_bilibili_www.kuangstudy.com_SpringBoot_Swagger_Swagger_Java_664386224_33512603f27829b1279b59de5c725510973b17cf.jpg_57w_57h_1c.png_https_www.bilibili.com_video_BV1Y441197Lw_spm_id_from_333.999.0.0]: https://www.bilibili.com/video/BV1Y441197Lw?spm_id_from=333.999.0.0
[Swagger_ Swagger_API]: https://gitee.com/DZ_QY/swagger
[fcb3007ee3014f439cde7b9a3e1a52cf.png]: https://img-blog.csdnimg.cn/fcb3007ee3014f439cde7b9a3e1a52cf.png
[e1de797061fc4ac28e4c965bff84afb1.png]: https://img-blog.csdnimg.cn/e1de797061fc4ac28e4c965bff84afb1.png
[d48ccc3dfe0f4639992d554f049e4b39.png]: https://img-blog.csdnimg.cn/d48ccc3dfe0f4639992d554f049e4b39.png
[fa481f3c0054431189ee0820c0820b89.png]: https://img-blog.csdnimg.cn/fa481f3c0054431189ee0820c0820b89.png
[af32e54c8b6540f58f6d689bad41764f.png]: https://img-blog.csdnimg.cn/af32e54c8b6540f58f6d689bad41764f.png
[374fe001256342d895d3015153240c94.png]: https://img-blog.csdnimg.cn/374fe001256342d895d3015153240c94.png
[af71bc55b0d740e7b40951eeee441774.png]: https://img-blog.csdnimg.cn/af71bc55b0d740e7b40951eeee441774.png
[9931f7c605dc4c1981e910f1fbd09782.png]: https://img-blog.csdnimg.cn/9931f7c605dc4c1981e910f1fbd09782.png
[b7dfb01ed1f44628a1d63472214266f8.png]: https://img-blog.csdnimg.cn/b7dfb01ed1f44628a1d63472214266f8.png
[e4e299e64e80448fb7ae9bf6465674d6.png]: https://img-blog.csdnimg.cn/e4e299e64e80448fb7ae9bf6465674d6.png
[f94d21cc9f9649748db1b74e5d9efb66.png]: https://img-blog.csdnimg.cn/f94d21cc9f9649748db1b74e5d9efb66.png
[51aa3d314b5114aee2f614c060c64e56.png]: https://img-blog.csdnimg.cn/img_convert/51aa3d314b5114aee2f614c060c64e56.png
[cf1a1583f2437707149543e408ab385b.png]: https://img-blog.csdnimg.cn/img_convert/cf1a1583f2437707149543e408ab385b.png
[32805a6ad74bcd701162c78f8a5e66af.png]: https://img-blog.csdnimg.cn/img_convert/32805a6ad74bcd701162c78f8a5e66af.png
[1dcc7a7ecfebe222c3c74a1967917804.png]: https://img-blog.csdnimg.cn/img_convert/1dcc7a7ecfebe222c3c74a1967917804.png