Swagger的学习笔记

清疚 2023-09-30 04:53 66阅读 0赞

### SpringBoot集成Swagger ###

在项目中使用Swagger需要springbox

*  swagger2
 *  ui

#### 使用swagger ####

1.  新建一个springboot项目
2.  导入依赖
    
    > 必须为2.9.2版本
    
        
        <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测试项目是否能够正常运行
4.  编写一个配置类-SwaggerConfig来配置 Swagger
    
        @Configuration
        @EnableSwagger2//开启Swagger2
        public class SwaggerConfig {
              
        }
5.  访问测试：http://localhost:8080/swagger-ui.html，可以看到swagger的界面
    
    > **如果启动时报空指针，将springboot的版本降到2.5.5即可**
    > 
    > **如果访问不了这个页面，则看一下导入的两个依赖版本是不是2.9.2**
    
    ![image-20220314152546275][]

#### 配置Swagger ####

1.  编写SwaggerConfig
    
        @Configuration
        @EnableSwagger2//开启Swagger2
        public class SwaggerConfig {
              
        
            //配置了Swagger的Docket的bean实例
            @Bean
            public Docket docket(){
              
                return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
            }
        
            //配置Swagger信息=apiInfo
            //配置文档信息
            private ApiInfo apiInfo(){
              
                //作者信息
                Contact contact = new Contact("lzj", "https://user.qzone.qq.com/1481315703/infocenter", "1481315703@qq.com");
        
                return new ApiInfo(
                        "lzj的SwaggferAPI文档",//标题
                        "这是文档的介绍",//描述
                        "1.0",//版本
                        "https://user.qzone.qq.com/1481315703/infocenter",//组织连接
                        contact,//联系人信息
                        "Apache 2.0",//许可
                        "http://www.apache.org/licenses/LICENSE-2.0",//许可链接
                        new ArrayList());//扩展
            }
        }
2.  进入网页测试：http://localhost:8080/swagger-ui.html
    
    ![image-20220314154408150][]

#### Swagger配置扫描接口 ####

1.  构建Docket时通过select()方法配置怎么扫描接口
    
        //配置了Swagger的Docket的bean实例
        @Bean
        public Docket docket(){
              
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    //RequestHandlerSelectors配置要扫描接口的方式
                    .apis(RequestHandlerSelectors.basePackage("com.lzj.controller"))
                    .build();
        }
2.  重启项目测试，由于我们配置根据包的路径扫描接口，所以我们只能看到一个类
    
    ![image-20220314155441531][]
3.  除了根据包的路径扫描接口，还有根据方法上的注解扫描、通过类上的注解扫描等方法
    
        //配置了Swagger的Docket的bean实例
        @Bean
        public Docket docket(){
              
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    //RequestHandlerSelectors配置要扫描接口的方式
                    //basePackage:指定要扫描的包
                    //any():扫描全部
                    //none():不扫描
                    //withClassAnnotation():扫描类上的注解，参数是一个注解的反射对象
                    //withMethodAnnotation():扫描方法上的注解
                 .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                    .build();
        }
4.  也可以配置接口的扫描过滤
    
        @Bean
        public Docket docket(){
              
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    //RequestHandlerSelectors配置要扫描接口的方式
                    //basePackage:指定要扫描的包
                    //any():扫描全部
                    //none():不扫描
                    //withClassAnnotation():扫描类上的注解，参数是一个注解的反射对象
                    //withMethodAnnotation():扫描方法上的注解
                    .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                
                    //paths():过滤    过滤什么路径
                	//配置如何通过path过滤,即这里只扫描请求以/lzj/开头的接口路径
                    .paths(PathSelectors.ant("/lzj/**"))
                    .build();
        }
5.  这里的可选值还有
    
        any() // 任何请求都扫描
        none() // 任何请求都不扫描
        regex(final String pathRegex) // 通过正则表达式控制
        ant(final String antPattern) // 通过ant()控制

#### 配置Swagger开关 ####

1.  通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了
    
        //配置了Swagger的Docket的bean实例
            @Bean
            public Docket docket(){
              
                return new Docket(DocumentationType.SWAGGER_2)
                        .apiInfo(apiInfo())
                        //配置是否启用Swagger，如果是false，在浏览器将无法访问
                        .enable(false)
                        
                        .select()
                        //RequestHandlerSelectors配置要扫描接口的方式
                        //basePackage:指定要扫描的包
                        //any():扫描全部
                        //none():不扫描
                        //withClassAnnotation():扫描类上的注解，参数是一个注解的反射对象
                        //withMethodAnnotation():扫描方法上的注解
                        .apis(RequestHandlerSelectors.basePackage("com.lzj.controller"))
                        .build();
            }
2.  如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示？
    
    application.properties
    
        spring.profiles.active=dev
    
    application-dev.properties
    
        server.port=8081
    
    application-pro.properties
    
        server.port=8082
    
    SwaggerConfig
    
        @Bean
        public Docket docket(Environment environment) {
              
           // 设置要显示swagger的环境
           Profiles of = Profiles.of("dev", "test");
           // 判断当前是否处于该环境
           // 通过 enable() 接收此参数判断是否要显示
           boolean b = environment.acceptsProfiles(of);
           
           return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(apiInfo())
              .enable(b) //配置是否启用Swagger，如果是false，在浏览器将无法访问
              .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
              .apis(RequestHandlerSelectors.basePackage("com.lzj.controller"))
               // 配置如何通过path过滤,即这里只扫描请求以/lzj开头的接口
              .paths(PathSelectors.ant("/lzj/**"))
              .build();
        }
3.  测试效果
    
    ![image-20220314163032636][]

#### 配置API文档的分组 ####

![image-20220314163456328][]

1.  如果没有配置分组，默认是default。通过groupName()方法即可配置分组
    
        @Bean
        public Docket docket(Environment environment) {
              
           return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
              .groupName("lzj") // 配置分组
               // 省略配置....
        }
2.  如何配置多个分组？配置多个分组只需要配置多个docket即可：
    
        @Bean
        public Docket docket1(){
              
            return new Docket(DocumentationType.SWAGGER_2).groupName("A");
        }
        @Bean
        public Docket docket2(){
              
            return new Docket(DocumentationType.SWAGGER_2).groupName("B");
        }
        @Bean
        public Docket docket3(){
              
            return new Docket(DocumentationType.SWAGGER_2).groupName("C");
        }
3.  测试
    
    ![image-20220314164044189][]

#### 实体配置 ####

1.  新建一个实体类User
    
    > **@ApiModel为类添加注释**
    > 
    > **@ApiModelProperty为类属性添加注释**
    
        @ApiModel("用户实体类")
        public class User {
              
            @ApiModelProperty("用户名")
            public String username;
            @ApiModelProperty("密码")
            public String password;
        }
2.  只要这个实体在**请求接口**的返回值上（即使是泛型），都能映射到实体项中
    
        @PostMapping("/getUser")
        public User user(){
              
            return new User();
        }
3.  测试
    
    ![image-20220314165228662][]

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

**@ApiModel为类添加注释**

**@ApiModelProperty为类属性添加注释**

#### 常用注解 ####

Swagger的所有注解定义在io.swagger.annotations包下

下面列一些经常用到的，未列举出来的可以另行查阅说明：

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

我们也可以给请求的接口配置一些注释

@ApiOperation("Hello控制类")
    @ResponseBody
    @GetMapping("/hello2")
    public String hello(@ApiParam("用户名") String username){
        
        return "hello"+username;
    }

![image-20220314165946662][]

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

相较于传统的Postman或Curl方式测试接口，使用swagger简直就是傻瓜式操作，不需要额外说明文档(写得好本身就是文档)而且更不容易出错，只需要录入数据然后点击Execute，如果再配合自动化框架，可以说基本就不需要人为操作了。

Swagger是个优秀的工具，现在国内已经有很多的中小型互联网公司都在使用它，相较于传统的要先出Word接口文档再测试的方式，显然这样也更符合现在的快速迭代开发行情。当然了，提醒下大家在正式环境要记得关闭Swagger，一来出于安全考虑二来也可以节省运行时内存。

#### 扩展：其他皮肤 ####

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

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

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

![图片][bd9a281d347e3b9f1b3b2d2ee2988845.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>

![图片][0e4d4155f9b5ececdeef2d028f498f4d.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>

![图片][57afc3cfcc27f6b8cb1ed0ad769cf4d9.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>

![图片][dee0147c7660328b9e2518f42d79e17d.png]

#### 总结 ####

1.  我们可以通过Swagger给一-些比较难理解的属性或者接口， 增加注释信息
2.  接口文档实时更新
3.  可以在线测试
4.  Swagger是一个优秀的工具, 几乎所有大公司都有使用它

g-ui **访问 http://localhost:8080/document.html**

![在这里插入图片描述][25ecd725719ce032e234663c4a6a8709.png_pic_center]

#### 总结 ####

1.  我们可以通过Swagger给一-些比较难理解的属性或者接口， 增加注释信息
2.  接口文档实时更新
3.  可以在线测试
4.  Swagger是一个优秀的工具, 几乎所有大公司都有使用它
    
    \*\*\[注意点\]\*\*在正式发布的时候，关闭Swagger! ! !

[image-20220314152546275]: https://img-blog.csdnimg.cn/img_convert/2dea9d2b9629601c0b57096d72e7b281.png
[image-20220314154408150]: https://img-blog.csdnimg.cn/img_convert/82df46d6231b959aacf3736537d35d66.png
[image-20220314155441531]: https://img-blog.csdnimg.cn/img_convert/8452868da3ba650ef774b3cd7defaa53.png
[image-20220314163032636]: https://img-blog.csdnimg.cn/img_convert/e677bbbdd9f8640c380c47af840a9c48.png
[image-20220314163456328]: https://img-blog.csdnimg.cn/img_convert/57bb2484fb262d830f60fb170eb20e1c.png
[image-20220314164044189]: https://img-blog.csdnimg.cn/img_convert/69f782e551c9751053b00a8672afb8a2.png
[image-20220314165228662]: https://img-blog.csdnimg.cn/img_convert/6763a83e71c4fb9b833c8a0c04404170.png
[image-20220314165946662]: https://img-blog.csdnimg.cn/img_convert/fbba21884d280905569b7b46234ddbf9.png
[bd9a281d347e3b9f1b3b2d2ee2988845.png]: https://img-blog.csdnimg.cn/img_convert/bd9a281d347e3b9f1b3b2d2ee2988845.png
[0e4d4155f9b5ececdeef2d028f498f4d.png]: https://img-blog.csdnimg.cn/img_convert/0e4d4155f9b5ececdeef2d028f498f4d.png
[57afc3cfcc27f6b8cb1ed0ad769cf4d9.png]: https://img-blog.csdnimg.cn/img_convert/57afc3cfcc27f6b8cb1ed0ad769cf4d9.png
[dee0147c7660328b9e2518f42d79e17d.png]: https://img-blog.csdnimg.cn/img_convert/dee0147c7660328b9e2518f42d79e17d.png
[25ecd725719ce032e234663c4a6a8709.png_pic_center]: https://img-blog.csdnimg.cn/img_convert/25ecd725719ce032e234663c4a6a8709.png#pic_center