作为参数给后端为空_后端 API 接口文档 Swagger 使用指南

前言

作为一个以前后端分离为模式开发小组，我们每隔一段时间都进行这样一个场景：前端人员和后端开发在一起热烈的讨论"哎,你这参数又变了啊","接口怎么又请求不通了啊","你再试试,我打个断点调试一下.."。可以看到在前后端沟通中出现了不少问题。

对于这样的问题,之前一直没有很好的解决方案，直到它的出现，没错...这就是我们今天要讨论的神器:swagger,一款致力于解决接口规范化、标准化、文档化的开源库，一款真正的开发神器。

一：swagger是什么？

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。

这个解释简单点来讲就是说，swagger是一款可以根据resutful风格生成的生成的接口开发文档，并且支持做测试的一款中间软件。

二：为什么要使用swaager?

2.1:对于后端开发人员来说

• 不用再手写WiKi接口拼大量的参数，避免手写错误
• 对代码侵入性低，采用全注解的方式，开发简单
• 方法参数名修改、增加、减少参数都可以直接生效，不用手动维护
• 缺点：增加了开发成本，写接口还得再写一套参数配置

2.2:对于前端开发来说

• 后端只需要定义好接口，会自动生成文档，接口功能、参数一目了然
• 联调方便，如果出问题，直接测试接口，实时检查参数和返回值,就可以快速定位是前端还是后端的问题

2.3：对于测试

• 对于某些没有前端界面UI的功能，可以用它来测试接口
• 操作简单，不用了解具体代码就可以操作
• 操作简单，不用了解具体代码就可以操作

三：如何搭一个swagger

3.1:引入swagger的依赖

目前推荐使用2.7.0版本,因为2.6.0版本有bug，而其他版本又没有经过验证

一：引入Swagger依赖库io.springfox    springfox-swagger2    2.7.0io.springfox    springfox-swagger-ui    2.7.0

3.2：springBoot整合swagger

@Configuration@EnableSwagger2public class SwaggerConfig {    @Bean    public Docket productApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .select()                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))  //添加ApiOperiation注解的被扫描                .paths(PathSelectors.any())                .build();    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder().title(”swagger和springBoot整合“).description(”swagger的API文档"