前言
在服务端开发过程中，开发人员往往会提供出来很多API接口供客户端开发人员使用，那么为了方便使用呢，开发人员会在开发接口的过程中同时维护一份文档，以说明每一个接口的访问方式、需要的参数、返回的结果等基本信息。
基于上述情况，诞生了许多API接口文档自动化生成工具，今天重点要说的就是其中的Swagger。
一、Swagger简介
Swagger说白了就是 Api框架，并且是号称当今世界上最流行的Api框架。（反正这东西就是必学呗）
Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。
作为一个开发人员，不管从事前端还是后端，Swagger可以说是必学了。
Swagger简介可以参考下这篇文章：https://www.jianshu.com/p/349e130e40d5
下面开始正文：
讲Swagger就要讲到前后端分离：
前后端分离
前端：完全脱离后端，前端独立开发，根据后端提供的接口可以事先设置一些假数据进行开发
后端：事先主要的控制层，业务逻辑，持久层，注重高可用，高并发，高扩展
前后端最后设置在不同的服务器上进行部署。
前后端分离开发是目前业界的web主流开发模式，所以两个组的文档设置就很重要，而swagger就是一个在线的接口API框架，支持多种语言。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
作用：
接口的文档在线自动生成。
功能测试。
Swagger是一组开源项目，其中主要要项目如下：
Swagger-tools: 提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架进行集成。
Swagger-js: 用于JavaScript的Swagger实现。
Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。
Swagger-ui： 一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
Swagger-codegen： 一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。
二、SpringBoot整合Swagger
1.新建一个SpringBoot Web项目
(新建SpringBoot项目的时候勾选上Spring Web即可)
注：记得配置下Maven和JDK的版本哦
没什么难度，傻瓜式操作，跳过~
2.导入依赖
如果前一步没有勾选上Spring Web这一步也可以手动导入Web的Maven依赖
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency>
我们导入2个Swagger相关的依赖：Swagger2和Swagger UI
代码如下：
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
3.建立Swagger的配置文件
import org.springframework.context.annotation.Configuration; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 // 开启Swagger2(开关) public class SwaggerConfig { }
我们先不对里面的值进行配置，它会有默认值的，先运行下看看结果。
启动SpringBoot之后访问：http://localhost:8080/swagger-ui.html
这个页面主要看这四部分的信息
4.在Swagger配置文件里配置ApiInfo
public class SwaggerConfig { //配置了Swagger的Docket实例 @Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()); } //配置Swagger信息——ApiInfo private ApiInfo apiInfo(){ //作者信息 Contact contact = new Contact("BookSea", "https://blog.csdn.net/bookssea", "123456789@qq.com"); return new ApiInfo( "码农BookSea_SwaggerAPI", "Api Documentation", "1.0", "https://blog.csdn.net/bookssea", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList() ); } }
上面的那个Contact的话，Swagger是有默认值的，不配置的话就是我们页面看到的那样，源码点进去我们可以看到
static { DEFAULT = new ApiInfo("Api Documentation", "Api Documentation", "1.0", "urn:tos", DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList()); }
即我们页面看到的那些信息，大家可以这些信息去一 一对应。
再次启动SpringBoot。访问：http://localhost:8080/swagger-ui.html#/
如下：
5.在Swagger配置文件里配置Docket实例
配置完了接口信息 ApiInfo我们再来配置下Docket实例。
如下：
相关的一些注释，我已经写上了，供大家参考
public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) //如果enable为false，则Swagger不能在浏览器中访问 // .enable(false) .select() //RequestHandlerSelectors,配置扫描接口的方式 //basePackage,指定要扫描的包 //any,扫描全部 //none,不扫描 //withClassAnnotation,扫描类上的注解，参数是一个注解的反射对象 //withMethodAnnotation,扫描方法上的注解 .apis(RequestHandlerSelectors.basePackage("com.example.springboot_swagger.controller")) //paths()。过滤什么路径 // .paths(PathSelectors.ant("/example/**")) .build(); }
配置完Docket实例之后，再写个接口
@RestController public class HelloController { @RequestMapping(value = "/hello") public String hello(){ return "hello"; } }
访问：http://localhost:8080/swagger-ui.html#/
这里有这么多的请求方式是因为我们没有指定@RequestMapping的请求方式，指定即可。
@RequestMapping(value = "/hello",method = RequestMethod.GET)
指定之后就OK啦，如下：
6.配置Swagger分组
起组名：
访问：http://localhost:8080/swagger-ui.html#/
配置Swagger分组
公司常常需要多人协同开发，多人协同开发的时候就需要多个分组
这些实例会被注入到IOC容器中。
访问端口，结果如下：
7.Swagger注解
我们再新建一个User实体类，并且完善一下接口，再添加上一些注解。
实体类
@ApiModel("用户类") //给类添加说明 public class User { @ApiModelProperty("用户名") //给参数添加说明 public String userName; @ApiModelProperty("密码") public String password; public String getUserName() { return userName; } public void setUserName(String userName) { this.userName = userName; } public String getPassword() { return password; } public void setPassword(String password) { this.password = password; } }
控制层接口
@RestController public class HelloController { //Operation接口 @ApiOperation("访问hello") //给接口添加说明 @RequestMapping(value = "/hello",method = RequestMethod.GET) public String hello( String name){ return "您好,"+name; } @RequestMapping(value = "/user",method = RequestMethod.POST) public User user(User user){ return user; } }
常用的注解一般就这几个，后面我加上了注释。
成功了~~，本篇文章就讲到这。
总结
Swagger是一个优秀的框架，几乎大公司都会用，接口文档可以实时更新。使用非常方便。 赶紧学起来~~。 仅仅观看代码印象不深刻，建议大家最好动手敲敲。 本篇文章Demo已上传Github
👇
老铁，如果有收获，请点个免费的赞鼓励一下博主
以上就是本篇文章的有关内容
骚等别划走，恰饭时间~
