swagger 2速成

在说swagger之前，不得不提前后端分离开发的概念。现如今，最流行的开发方式是 vue + springbot 协同开发。vue作为最流行的渐进式框架，它只关心视图层（soc关注度分离原则）与第三方库做交互，有着双向绑定的特点。springboot 不用多说，它是当前最流行的后端框架！

目录

前后端分离

前后端分离的优点

容易产生的问题

解决方案

swagger的特点和概念

在springboot中集成swagger

搭建项目

配置swagger

配置扫描接口和开关

如何设置我的swagger在生产环境中使用 在发布的时候不使用

分组和接口注释

总结

---

前后端分离

在过去的后端时代，后端人员是主力，前端只需要管理静态页面，写html，甚至只需要使用画图工具即可完成开发，工作量少，薪资低。而后端的工作就很多了，要先把前端人员提供的html用模板引擎构建出来，如jsp等，然后才能进行接下来的操作。

而现在，前后端分离时代来了，不仅后端有分层开发，前端也有！

• 后端：后端控制层，服务层，数据访问层
• 前端：前端控制层，视图层

对于现在的前端人员，通过伪造的数据，在没有后端提供数据的前提下，也能把项目跑起来！

那么，现在用什么方式交互前后端呢？--》 api 接口 ，后端人员提供接口，前端从接口中获取数据渲染到页面上，实现前后端分离开发

前后端分离的优点

• 前后端彼此相对独立，耦合度低，前后端甚至可以部署在不同的服务器上
• 人员分工更加明确，项目开发速度快，效率高

容易产生的问题

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

解决方案

• 制定提纲，实时更新最新api，降低集成的风险
• 早些年，使用word制定计划，虽然提取下载文档操作不方便，但也算是解决了这个问题
• 后来，使用一些第三方工具来快速获取接口中的内容，如 postman
• 现在，swagger！

swagger的特点和概念

• swagger号称世界上最流行的api框架
• 使用restful 风格的api 文档在线自动生成工具 api 文档与 api 定义同步更新
• 直接运行，可以在线测试api接口
• 支持多种语言

官网

在springboot中集成swagger

• 在项目中使用需要引入springfox相关jar包
• 配置swagger2
• 访问swagger-ui

搭建项目

1. 新建一个springboot项目 --web项目
2. 去maven官网找需要用的jar包

   
   
       io.springfox
       springfox-swagger2
       2.9.2
   
   
   
       io.springfox
       springfox-swagger-ui
       2.9.2
   

3. 编写一个hello world
4. 配置swagger==》config 开启swagger2 enableSwagger2

   @Configuration
   @EnableSwagger2 //开启swagger2
   public class swaggerConfig {
   
   }

5. 访问测试  http://localhost:8080/swagger-ui.html

如果出现404无法访问的情况，修改依赖版本为2.9.2即可，博主之前用的3.0.0就出现了这个问题

配置swagger

• swagger配置类里有 bean实例docket

@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("赵敬轩","123","[email protected]");
        return new ApiInfo(
                "赵敬轩的接口文档",
                "大隐隐于市，努力即成功",
                "1.0",
                "123",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }

}

配置扫描接口和开关

通过docket中的select()方法可以配置要扫描哪些接口 ，每一个select()方法都要对应一个build()方法，有 select() 就必须要有build()

 例如 扫描GetMapping接口

//配置了swagger的docket的bean实例
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
            .build();
}

controller

@Controller
public class helloSwagger {
    @ResponseBody
    @RequestMapping("hello")
    public String hello(){
        return "hello,swagger";
    }
    @ResponseBody
    @GetMapping("hi")
    public String hi(){
        return "hi";
    }
}

效果

 扫描的规则

• RequestHandlerSelectors配置要扫描接口的方式
• basePackage指定要扫描的包
• any()扫描全部
• none()不扫描
• withClassAnnotation 扫描类上的注解 参数是一个注解的反射对象
• withMethodAnnotation 扫描方法上的注解

修改 GetMapping 为 RequestMapping、

RequestMapping() 如果不指定请求方式，默认全部请求一遍get,post,head,put,delete..

 

在扫描代码段后可以接过滤器

paths 过滤哪些路径

如何设置我的swagger在生产环境中使用 在发布的时候不使用

• 判断是不是生产环境
• enable

1.新建环境文件，prod和dev

  

2.主properties里激活生产环境

3.配置swaggerConfig

  

4.测试

 

分组和接口注释

分组

修改组名

 

 添加组员

/**
 * 添加组员
 */
@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("小明");
}
 @Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("小张");
}
 @Bean
public Docket docket3(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("小李");
}

 效果

接口注释 

为实体类和属性添加注释 

为接口方法添加注释

效果

 

  

 测试

接口使用测试

 

 

报错测试

 

 

总结

swagger简单容易上手是他最大的优点，与postman对比，体积更小，集成在项目中，项目成员更容易协调沟通。swagger集文档注解，接口注释，实时测试功能于一身，是现如今最火爆的框架！

需要注意的是，在项目正式上线后，要关闭swagger文档，这样不但可以防止接口信息被暴露，而且可以加快项目运行速度。