Swagger基本介绍

无论是前端还是后端开发，都或多或少地被接口文档折磨过，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码来，也不喜欢写注释。

所以随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了，这时候Swagger就出现了。

Swagger基本介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

作用

1.支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便。

2.提供 Web 页面在线测试 API：Swagger 生成的文档支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

Swagger开源工具

Swagger Codegen

通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多种语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。

Swagger UI

提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

Swagger Editor

类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

Swagger Inspector

它是一个可以对接口进行测试的在线版postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。

Swagger Hub

集成了上面所有项目的各个功能，开发者可以以项目和版本为单位，将其描述文件上传到Swagger Hub中。

SpringBoot集成Swagger

环境：jdk 1.8 + swagger2

1.Maven依赖

1.<dependency>  
2.    <groupId>io.springfox</groupId>  
3.    <artifactId>springfox-swagger2</artifactId>  
4.    <version>2.9.2</version>  
5.</dependency>  
6.<dependency>  
7.    <groupId>io.springfox</groupId>  
8.    <artifactId>springfox-swagger-ui</artifactId>  
9.    <version>2.9.2</version>  
10.</dependency>

2.配置类

1.@Configuration  
2.@EnableSwagger2  // 开启Swagger2  
3.public class SwaggerConfig {  
4.  
5.  //配置docket以配置Swagger具体参数，Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。
6.    @Bean  
7.    public Docket docket() {
8.        //Docket 实例关联上 apiInfo()，构建Docket时通过select()方法配置怎么扫描接口
9.        return new Docket(DocumentationType.SWAGGER_2)  
10.                .apiInfo(apiInfo())  
11.                .select()  
12.                .apis(RequestHandlerSelectors.basePackage("com.yid.demo.controller"))  
13.                .build();  
14.    }  
15.  
16.      //配置文档信息，  通过apiInfo()属性配置文档信息。
17.        private ApiInfo apiInfo() {  
18.            //作者信息  
19.            Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");  
20.  
21.            return new ApiInfo(  
22.                    "Swagger学习", // 标题  
23.                    "学习演示如何配置Swagger", // 描述  
24.                    "v1.0", // 版本  
25.                    "http://terms.service.url/组织链接", // 组织链接  
26.                    contact, // 联系人信息  
27.                    "Apach 2.0 许可", // 许可  
28.                    "许可链接", // 许可连接  
29.                    new ArrayList<>()// 扩展  
30.            );  
31.        }  
32.}

3.用户实体类（get，set方法省略）

1.@ApiModel("用户实体类")  
2.public class User {  
3.    @ApiModelProperty("用户名")  
4.    private  String username;  
5.    @ApiModelProperty("密码")  
6.    private  String password;  
7.}  

4.控制层

1.@RestController  
2.public class HelloController {  
3.  
4.    @ApiOperation("get测试")  
5.    @GetMapping("/get")  
6.    public User hello2(@ApiParam("用户") User user) {  
7.        return user;  
8.    }  
9.}  

5.常用注解

6.测试步骤
我们打开get方法：可以看出方法的请求参数清晰地罗列出来，包括方法的返回值。并且有一个很重要的功能，只需要点下方的try it out就可以进行接口测试。

按下图顺序操作

即可得到测试结果如下

参考资料：Swagger官网: https://swagger.io