前言

说起Swagger就不得不说前后端分离

当前最主流的前后端分离技术栈：Vue+Springboot

后端时代：

前端只用管理静态页面:html

最后统一交给后端，后端将其修改为jsp，在整个过程中，后端充当主力

前后端分离时代：

后端：后端控制层，服务层，数据访问层【后端团队】

前端：前端控制层，视图层【前端团队】

前端可以自定义一些伪后端数据：json,在写的时候就存在，不需要后端，前端工程依旧能够跑起来

那么前端后端如何交互？
此时我们可以考虑API

前后端分离好处：

产生的问题：

解决方式：

前端测试后端接口：postman

后端提供接口，需要实时更新最新的消息及改动

在项目当中使用Swagger需要springbox；

一、Swagger

官网地址：http://swagger.io/

二、SpringBoot集成Swagger

1.新建一个SpringBoot = web项目

2.导入依赖

io.springfoxspringfox-swagger22.9.2
 io.springfoxspringfox-swagger-ui2.9.2
 

3.集成Swagger ==>Config

@EnableSwagger2 用来开启Swagger2

@Configuration
 @EnableSwagger2 //开启Swagger2
 public class SwaggerConfig {}
 

4.进入测试

http://localhost:8080/swagger-ui.html

配置Swagger

# 配置Swagger基本信息 Swagger的Bean实例Docket:

package com.fwp.swagger.config;import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import springfox.documentation.builders.PathSelectors;
 import springfox.documentation.builders.RequestHandlerSelectors;
 import springfox.documentation.service.ApiInfo;
 import springfox.documentation.service.Contact;
 import springfox.documentation.spi.DocumentationType;
 import springfox.documentation.spring.web.plugins.Docket;
 import springfox.documentation.swagger2.annotations.EnableSwagger2;import java.util.ArrayList;@Configuration
 @EnableSwagger2 //开启Swagger2
 public class SwaggerConfig {//配置了Swagger的Docket的Bean实例@Beanpublic Docket docket(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()//RequestHandlerSelectors配置要扫描接口的方式//basePackage指定要扫描的包//any() 扫描全部//none() 都不扫描//withClassAnnotation() 扫描类上的注解,参数是一个注解的反射对象//withMethodAnnotation() 扫描上的注解,参数是一个注解的反射对象.apis(RequestHandlerSelectors.basePackage("com/fwp/swagger/controller")).paths(PathSelectors.ant("/fwp/**")).build();}//配置Swagger信息=apiInfoprivate ApiInfo apiInfo(){//作者信息Contact contact = new Contact("鹏鹏", "https://blog.csdn.net/weixin_51132678?type=blog", "3230609771@qq.com");return new ApiInfo("鹏鹏的SwaggerAPI文档","即使再小的船也能上岸","1.0","https://blog.csdn.net/weixin_51132678?type=blog",contact,"Apache 2.0","http://www.apache.org/licenses/LICENSE-2.0",new ArrayList());}
 }
 

三、Swagger配置扫描接口

Docket.select()

//配置了Swagger的Docket的Bean实例
 @Bean
 public Docket docket(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()//RequestHandlerSelectors配置要扫描接口的方式//basePackage指定要扫描的包//any() 扫描全部//none() 都不扫描//withClassAnnotation() 扫描类上的注解,参数是一个注解的反射对象//withMethodAnnotation() 扫描方法上的注解,参数是一个注解的反射对象.apis(RequestHandlerSelectors.basePackage("com.fwp.swagger.controller"))//过滤.paths(PathSelectors.ant("/fwp/**")).build();
 }
 

配置是否启动swagger

enable是否启动swagger。如果为false，则swagger在浏览器中不能访问

 //配置了Swagger的Docket的Bean实例@Beanpublic Docket docket(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(false)
 

swagger启动失败

那么如果我们希望Swagger在某一个环境中使用，在其他时候不使用怎么办

dev环境下：

server.port=8081

pro环境下：

server.port=8082

application.properties文件

spring.profiles.active=dev

此时我们处于dev环境下，我们希望swagger在dev环境下能使用，在其他环境下不能使用

@Configuration
 @EnableSwagger2 //开启Swagger2
 public class SwaggerConfig {//配置了Swagger的Docket的Bean实例@Beanpublic Docket docket(Environment environment){//设置要显示的Swagger环境  可返回多个Profiles profiles = Profiles.of("dev","test");//获取生产环境//通过environment.acceptsProfiles(profiles)判断自己是否处在指定环境boolean flag = environment.acceptsProfiles(profiles);System.out.println(flag);return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(flag)//enable是否启动swagger。如果为false，则swagger在浏览器中不能访问.select().apis(RequestHandlerSelectors.basePackage("com.fwp.swagger.controller"))//过滤//.paths(PathSelectors.ant("/fwp/**")).build();}//配置Swagger信息=apiInfoprivate ApiInfo apiInfo(){//作者信息Contact contact = new Contact("鹏鹏", "https://blog.csdn.net/weixin_51132678?type=blog", "3230609771@qq.com");return new ApiInfo("鹏鹏的SwaggerAPI文档","即使再小的船也能上岸","1.0","https://blog.csdn.net/weixin_51132678?type=blog",contact,"Apache 2.0","http://www.apache.org/licenses/LICENSE-2.0",new ArrayList());}
 }
 

将enable()中的参数值设置为flag，这样当我们处于dev与test环境下时swagger默认开启，其他情况下默认关闭
进入dev环境

进入pro环境

四、配置API文档分组

return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("鹏鹏")
 

如果我们想配置多个分组怎么办呢？
创建多个docket对象，设置不同的组名

    @Beanpublic Docket docket1(){return new Docket(DocumentationType.SWAGGER_2).groupName("A");}@Beanpublic Docket docket2(){return new Docket(DocumentationType.SWAGGER_2).groupName("B");}@Beanpublic Docket docket3(){return new Docket(DocumentationType.SWAGGER_2).groupName("C");}
 

可以看见页面中出现了不同的组别，每个组别之间互不干扰，利于合作开发，每个人扫描自己的包，做自己的事情

五、实体类的配置

User类

@Data
 @AllArgsConstructor
 @NoArgsConstructor//@Api("注释")
 @ApiModel("用户实体类")
 public class User {@ApiModelProperty("用户名")public String username;@ApiModelProperty("密码")public String password;
 }
 

HelloController中：

//只要返回值中存在实体类，他就会被扫描到Swagger中
 @PostMapping("/user")
 public User user(){return new User("pp","123");
 }
 

文档注解

为了方便交互，方便文档阅读，我们可以为文档添加说明信息

实体类

@Data
 @AllArgsConstructor
 @NoArgsConstructor//@Api("注释")
 @ApiModel("用户实体类")
 public class User {@ApiModelProperty("用户名")public String username;@ApiModelProperty("密码")public String password;
 }
 

HelloController:

@RestController
 public class HelloController {@GetMapping("/hello")public String hello(){return "hello!!!";}//只要返回值中存在实体类，他就会被扫描到Swagger中@PostMapping("/user")public User user(){return new User("pp","123");}//Operation接口   放在方法上而不是类上@ApiOperation("Hello控制类")@GetMapping("/hello2")public String hello2(@ApiParam("用户名") String username){return "hello!!!"+username;}
 

添加注释后展示：

总结

1. 我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息
2. 接口文档实时更新
3. 可以在线测试

注意点：
在正式发布的时候，需要关闭Swagger，一是出于安全考虑，，二是节省内存