Swagger2+springboot自动生成接口文档

百度安全验证https://baijiahao.baidu.com/s?id=1615175862715619117&wfr=spider&for=pc

Swagger2 自动生成接口文档_javafollowers的博客-CSDN博客

显示不同风格的接口文档地址：

(17条消息) Swagger之导入不同的pom依赖访问不同的html展示不同的UI界面_超超向的博客-CSDN博客_swagger的pom

添加全局header：

(17条消息) swagger2-身份认证Authenticatio（二）ApiKey_中国lanwp的博客-CSDN博客_apikey swagger

swagger-ui配置添加Authorization - 和我紫晨 - 博客园 (cnblogs.com)

(17条消息) springboot集成swagger-bootstrap-ui实现Authorize 功能_BellCalderon的博客-CSDN博客

spring boot项目中使用swagger2 - 简书

SpringBoot2.x添加拦截器后Swagger无法访问_Strugglein的博客-CSDN博客_springboot swagger无法访问//放行swagger

为什么使用
公司服务器程序需要给移动端App等提供数据访问接口，之前接口信息都是使用word文档提供给前端人员使用，后来发现后台稍微修改一下，就需要更改一次文档，有时候修改不及时或者遗漏，容易造成前端和后台接口不一致，因此，后来决定尝试一下使用Swagger2来进行接口文档的描述。事实证明，这样的做法有利于工作效率的提高和前后台人员的沟通。

效果图

本次demo是使用Spring boot来做的，好处是搭建快，使用传统的方式跟这个差不多。

在pom.xml中添加依赖
 <!--  引入swagger包 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
        </dependency>
1
2
3
4
5
6
7
8
9
10
11
编写Swagger2的config
新增SwaggerConfig类，进行Swagger2的配置。

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hhm.workswagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo getApiInfo(){
        return new ApiInfoBuilder()
                .title("大标题")
                .description("小标题")
                .version("1.0")
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .build();
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
通过@Configuration和@EnableSwagger2注解就可以使用启用Swagger2的使用了，不过要想显示具体接口的信息，需要在controller中添加注解才能够在Swagger2中展现。

在controller中添加注解

@RestController
@Api(value = "/person", tags = "我的接口模块")
public class PersonController {

    @Autowired
    PersonJpa personJpa;

    private Logger log = LoggerFactory.getLogger(PersonController.class);

    @ApiOperation(value = "查询Person")
    @GetMapping("/query")
    public List<Person> queryUser() {
        List<Person> list = personJpa.findAll();
        log.error("Person信息：" + list.toString());
        return list;
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
一些注解的使用
@Api：用在类上，说明该类的作用

@ApiOperation：用在方法上，说明方法的作用，标注在具体请求上，value和notes的作用差不多，都是对请求进行说明；tags则是对请求进行分类的，比如你有好几个controller，分别属于不同的功能模块，那这里我们就可以使用tags来区分了，看上去很有条理

@ApiImplicitParams：用在方法上包含一组参数说明

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

　　paramType：参数放在哪个地方

　　header 请求参数的获取：@RequestHeader

　　query 请求参数的获取：@RequestParam

　　path（用于restful接口） 请求参数的获取：@PathVariable

　　body（不常用）

　　form（不常用）

　　name：参数名

　　dataType：参数类型

　　required：参数是否必须传

　　value：参数的意思

　　defaultValue：参数的默认值

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

　　code：数字，例如400

　　message：信息，例如”请求参数没填好”

　　response：抛出异常的类

@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）表明这是一个被swagger框架管理的model，用于class上 
@ApiModel：使用在实体类上，描述实体类。 
@ApiModelProperty ：使用在实体类上的成员变量上，描述成员变量的含义。

到这里就可以运行程序进行测试了，访问 http://127.0.0.1:8080/swagger-ui.html 就可以看到上面显示的页面了。

点击try it out!就可以得到进行测试，得到服务器返回的数据。 

总结
使用Swagger2在一定程度上可以提高开发效率，后台开发人员不需要去维护接口文档（特别是接口文档多了以后很难及时更新），减少了部分的工作量，可以把更多的精力放在业务逻辑上。但是，使用Swagger2也有不好的地方，因为需要使用好多的注解，会导致controller层的代码阅读起来不是很清晰。（纯粹是个人观点）

一、简介

在当下这个前后端分离的技术趋势下，前端工程师过度依赖后端工程师的接口和数据，给开发带来了两大问题：

问题一、后端接口查看难：要怎么调用？参数怎么传递？有几个参数？参数都代表什么含义？问题二、返回数据操作难：数据返回不对或者不够怎么办？怎么才能灵活的操作数据？

这是很多公司前后端分离之后带来的困扰，那怎么来解决这些问题？

问题一的一般解决方案：后端团队共同维护一个在线文档，每次改接口再去改对应的文档，但难免会遗漏，花的大力气但却效果平平。

问题二的一般解决方案：自己搭建一个Mock服务器，然后一个接口一个接口手动去录规则，还是一个费力的体力活。

那有没有最优的解决方案，来解决以上两个问题呢？答案是肯定的，那就是将要登场的“Swagger”和“Easy Mock”。

1.1 Swagger介绍

Swagger是全球最流行的接口文档自动生成和测试的框架，几乎支持所有的开发语言。

Swagger官网地址：https://swagger.io/

1.2 Easy Mock介绍

Easy Mock是一个可视化，并且能快速生成 模拟数据的持久化服务。

Easy Mock能一键导入Swagger所有接口，省去了手动录制接口的麻烦，而且能够完美的适配Swagger中的代码注释，可谓开发利器。

Easy Mock数据是保存在云端的，而且可以创建团队项目，可以真正的实现前端脱离后端进行项目开发。

接下来一起来看看怎么在项目中集成Swagger和Easy Mock吧。

1.3 开发环境

JDK 8Spring Boot 2.0.4Swagger 2.9.2IDEA 2018.2

二、Swagger集成

本文介绍的Swagger是基于Spring Boot框架的，一起来看具体的实现步骤。

2.1 添加依赖

配置pom.xml，添加如下代码：

其中：

springfox-swagger2 用于JSON API文档的生成；springfox-swagger-ui 用于文档界面展示。

更多版本请访问：

springfox-swagger2：http://mvnrepository.com/arti...

springfox-swagger-ui：http://mvnrepository.com/arti...

2.2 注册Swagger

在源码的根目录也就是Appliction.java的同级目录，创建Java类“SwaggerConfig.java”（命名无所谓），代码如下：

其中“@ConditionalOnExpression”为Spring的注解，用户是否实例化本类，用于是否启用Swagger的判断（生产环境需要屏蔽Swagger）。

2.3 生产环境禁用Swagger

是否启用Swagger是在application.properties文件里配置的，配置如下：

swagger.enable=true

生产环境禁用，设置为false即可。

2.4 添加文档注释

完成以上三个步骤，已经完成了Spring Boot对Swagger的集成，但是文档不够友好，比如类、接口的中文说明、参数的说明，是没有的，需要在代码中完成。

如下代码：

写完代码运行项目，在浏览器输入：http://localhost:8080/swagger-ui.html 查看添加注释的效果，如下图：

其中@Api是用来描述类的，@ApiOperation是用来描述方法的，@ApiImplicitParam是用来描述参数的，更多注解说明请看下文。

示例源码下载：https://github.com/vipstone/s...

三、Swagger文档注解

我们现在已经对Swagger有了初步的认识，本节重点来看Swagger注解的使用。

Swagger注解的作用是给接口添加注释的。

3.1 @Api 类注释

@Api：用来描述类的，属性如下：

tags 描述类的用途value 对显示而言没有任何用途可以不用设置

代码示例：

@Api(tags = "文章接口")

3.2 @ApiOperation 方法注释

@ApiOperation：用来描述方法的，属性如下：

value 方法的描述notes 方法备注说明

代码示例：

@ApiOperation(value = "获取所有文章", notes = "查询分页数据")

效果如下图：

3.3 @ApiImplicitParams 参数注释

@ApiImplicitParams：描述多参数

@ApiImplicitParam：描述单参数

属性如下：

name 参数value 参数的描述required 是否必传paramType 参数存放位置：header、query、path(resuful接口)、body、formdataType 参数类型defaultValue 参数默认值

代码示例：

效果如下图：

3.4 @ApiModel 实体对象描述

@ApiModel：实体类名描述，属性如下：

description 类描述

@ApiModelProperty：字段描述，属性如下：

value 字段描述

示例如下：

四、Easy Mock使用

Easy Mock是在线的Mock（模拟）服务器，注册账号即可使用，数据存储云端，使用简单不需要在本地进行任何配置，具体操作步骤如下文。

4.1 注册账号

浏览器输入：https://easy-mock.com/login 注册账号

4.2 配置Easy Mock项目

进入管理页面之后，点击演示个人演示项目（默认创建的可以直接拿来用），如下图：

进入接口列表，点击设置=>点击Swagger Docs API选择Upload（本地文件上传），如下图：

4.3 导出Swagger接口

浏览器访问：http://localhost:8080/v2/api-docs 就看到项目的所有接口JSON格式的，右键另存为文件，如下图：

继续4.2的操作，上传刚刚保存的JSON文件到Easy Mock。

4.4 更新接口

保存完JSON数据之后就返回到项目的设置页了，这个时候点击“同步Swagger”就看到所有接口了。如下图：

到此为所有的接口已经导入了，可以点击接口列表右侧的复制按钮，进行愉快的调用了。

这个时候就可以完全脱离后端了，点击接口详情，可以看出Easy Mock完美识别了Swagger注释也有了，如下图：

4.5 修改数据

接口的调用没问题，接下来就是修改操作数据了，点击右侧的相应接口的修改按钮，如下图：

进入编辑页面，你现在编辑的数据就是接口要返回的数据，数据是JSON格式的，并且是在线保存云端，无须担心数据丢失，如下图：

编辑完直接点击更新接口即可，注意编辑页面还有一个预览按钮，点入可以模拟请求，这下连Postman都省了，效果如下：

五、总结

到此为止所有内容已经演示完了，我们解决前后端分离带来接口管理难、数据操作难的问题。自动生成接口文档、一键模拟数据，让我们不再依赖后端，只专注前端的业务，等后端把接口写完之后，再进行联合调试就可以了，这样我们就不费吹灰之力搞定了所有难题，并且灵活的配置让我们可以不影响和污染生产环境，生产环境设置禁用Swagger即可，并且有了预览功能之后我们甚至连Postman都省了。