Swagger详解

文章目录

• 前言
• 一、Swagger简介
• 二、SpringBoot集成Swagger
• 三、配置Swagger
  • SwaggerConfig中重写方法
  • 通过apiInfo()属性配置文档信息
  • Docket 实例关联上 apiInfo()
  • 重启后，访问测试 http://localhost:8080/swagger-ui.html
  • .易错点（之前试了很久都不好用，原因竟然是因为.....）
• 四、配置扫描接口
  • 构建Docket时通过select()方法配置怎么扫描接口
  • 如何配置接口扫描过滤
• 五、配置开关Swagger
  • 如何开启/关闭swagger
  • 面试题

总结

---

前言

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

---

一、Swagger简介

前后端分离

• 前端 -> 前端控制层、视图层

• 后端 -> 后端控制层、服务层、数据访问层

• 前后端通过API进行交互

• 前后端相对独立且松耦合

产生的问题

• 前后端集成，前端、后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发

解决方案

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

Swagger

• 号称世界上最流行的API框架

• Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新

• 直接运行，在线测试API

• 支持多种语言 （如：Java，PHP等）

• 官网：https://swagger

二、SpringBoot集成Swagger

前提：要求：jdk 1.8 + 否则swagger2无法运行

步骤1：新建一个SpringBoot-web项目

步骤2：添加Maven依赖(pom文件)

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

步骤3：创建基础的SwaggerConfig类

//该类作为项目的配置文件类
@Configuration
//配置swagger启动
@EnableSwagger2
public class SwaggerConfig {

}

步骤4：启动类中增"@EnableSwagger2”注解

注意：如果启动类上面不增加这个注解，会有下面的报错。

步骤5：重启后，访问：http://localhost:8085/swagger-ui.html

 

 三、配置Swagger

1.SwaggerConfig中重写方法

备注：Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。

 @Bean
//配置docket以配置Swagger具体参数
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2);
}

2. 通过apiInfo()属性配置文档信息

备注：在SwaggerConfig中书写apiInfo()方法

//配置文档信息
 private ApiInfo apiInfo() {
    Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人 访问链接", "联系人邮箱");
    return new ApiInfo("Swagger学习", // 标题
           "学习演示如何配置Swagger", // 描述
           "v1.0", // 版本
           "http://terms.service.url/组织链接", // 组织链接 contact
           contact,//联系人
           "Apach 2.0 许可", // 许可
           "许可链接", // 许可连接
           new ArrayList<>()// 扩展
    );
}

3. Docket 实例关联上 apiInfo()

备注：在SwaggerConfig中将docket重写方法

    //配置docket以配置Swagger具体参数
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

备注：目前你的SwaggerConfig中应该是这个样子的

//该类作为项目的配置文件类
@Configuration
//配置swagger启动
@EnableSwagger2
public class SwaggerConfig {
    //配置docket以配置Swagger具体参数
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

    //配置文档信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人 访问链接", "联系人邮箱");
        return new ApiInfo("Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接 contact
                contact,//联系人
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }
}

4. 重启后，访问测试 http://localhost:8080/swagger-ui.html 

 5.易错点（博主之前试了很久都不好用，原因竟然是因为.....）

注意：这里将启动类一定放在外层！！！！！！！！！！！！！！！！！！！

 四、配置扫描接口

1. 构建Docket时通过select()方法配置怎么扫描接口

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
   .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors 配置如何扫描接口
   .apis(RequestHandlerSelectors.basePackage("com.example.controller"))//只扫描该包下面的接口
   .build();
}

注意：除了扫描指定包的接口外，还有如下配置。

• any () // 扫描所有，项目中的所有接口都会被扫描到
• none () // 不扫描接口
• // 通过方法上的注解扫描，如 withMethodAnnotation(GetMapping.class) 只扫描 get 请求
• withMethodAnnotation ( final Class <? extends Annotation > annotation )
• // 通过类上的注解扫描，如 .withClassAnnotation(Controller.class)只扫描有controller 注解的类中的接口
• withClassAnnotation ( final Class <? extends Annotation > annotation )
• basePackage ( final String basePackage ) // 根据包路径扫描接口

2. 如何配置接口扫描过滤

目的：只有接口url中带有这个路径才可以被扫描到

 //配置docket以配置Swagger具体参数
@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
    .apiInfo(apiInfo()).select()// 通过.select()方法，去配置扫描接 口,RequestHandlerSelectors配置如何扫描接口
    .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 只臊面该包下面的接口
    .paths(PathSelectors.ant("/example/**")).build();//过滤带有指定路径的接口
}

备注：这里还可以选择

• any() // 任何请求都扫描
• none() // 任何请求都不扫描
• regex(final String pathRegex) // 通过正则表达式控制
• ant(final String antPattern) // 通过ant()控制

注意:配置的.paths(PathSelectors.ant()，必须是方法接口类上的才可以

五、配置开关Swagger

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

//配置docket以配置Swagger具体参数
@Bean
public Docket docket() {
  return new Docket(DocumentationType.SWAGGER_2)
     .apiInfo(apiInfo())
     .enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问
     .select()// 通过.select()方法，去配置扫描接 口,RequestHandlerSelectors配置如何扫描接口
     .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 只臊面该包下面的接口
     .paths(PathSelectors.ant("/yq/**"))//只扫描带有“/yq”路径的请求
     .build();
}

效果如下 

 面试题：

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

解题思路：

1.获取当前属于哪个环节（使用Environment对象 ）

2.判断是否是指定环境

3. 可以在项目中增加一个 dev 的配置文件查看效果！

//配置docket以配置Swagger具体参数
@Bean
public Docket docket(Environment environment) {
   // 设置要显示swagger的环境
   Profiles of = Profiles.of("dev", "test");
   // 判断当前是否处于哪个环境
   boolean env = environment.acceptsProfiles(of);
   return new Docket(DocumentationType.SWAGGER_2)
       .apiInfo(apiInfo())
       .enable(env) //配置是否启用Swagger，如果是false，在浏览器将无法访问
       .select()// 通过.select()方法，去配置扫描接 口,RequestHandlerSelectors配置如何扫描接口
       .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 只臊面该包下面的接口
       .paths(PathSelectors.ant("/yq/**"))//只扫描带有“/yq”路径的请求
       .build();
}

记得在代码里增加一个或者多个环境进行测试下哦！！

---

总结

提示：这里对文章进行总结：
例如：以上就是今天要讲的内容，本文仅仅简单介绍了pandas的使用，而pandas提供了大量能使我们快速便捷地处理数据的函数和方法。