springboot整合swagger，前后端接口规范

　　在我们的实际开发中，费事写完一个接口之后，还要维护该接口的接口文档，接口少还好说，当接口数量很多，维护接口文档也会是一个很繁重的任务。还有一点就是在我们修改完一个接口后，我们经常忘记把修改的内容添加到接口文档之内，或者我们添加了但前端同学没有及时注意到，所以这就会造成前后端的接口信息不同步，影响开发进度以及质量。这两天我简单总结了一下swagger2和springboot的整合。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。

 

1、创建一个springboot项目

2、添加swagger2的maven依赖

3、创建swagger的配置类，在appliacation的同级目录下创建swagger类

通过@configuration注解，让spring来加载此类的配置。basePackage内的包名也就是，接口存在的包，swagger会扫描并显示其下的接口

*注意，应该在springboot的Application类下添加@EnableSwagger2注解来启用swagger2

4、接下来就可以通过使用注解，在接口类中添加文档内容

@Api  用于controller类上   对类的功能进行描述

@ApiOperation  用在controller方法上  对类的方法进行描述

@ApiImplicitParam 用在Controller方法上 对方法需要传进来的参数进行描述

　　paramType 有path以地址形式提交数据、query直接跟参数完成自动映射赋值（get方法使用）、body以流的形式提交仅支持POST（@requestBody）、header参数在request headers里面提交、form以form表单形式提交仅支持POST，dataType如果是自定义的实体对象，需要在请求参数时加上@requestBody注解

@ApiImplicitParams  用在controller方法上，如果一个方法有多个请求参数，需要有该注解将@ApiImplicitParam包在里面

@ApiResponse 用在controller方法上，定义返回的错误号，以及其表达的含义

@ApiResponses 用在controller方法上， 当需要定义多个@ApiResponse时，需要用到该注解将它们包在里面

@ApiModel 用在返回对象类上   描述返回对象的意义

@ApiModelProperty 用在实体对象的字段上 用于描述字段含义

 

 5、接下来访问  http://localhost:8080/swagger-ui.html#/ 可以看到生成的文档页

6、点击查看相应的方法对应的生成接口文档

7、当然你还可以点击下面的 try it out来检验该接口是否可以正常访问

总结：

这只是简单总结了springboot整合swagger的简单用法，如果以后工作学习中碰到了更深层次的东西也会及时补充的。