对于接口服务来说接口文档极其重要，在团队配合和后续维护中占据重要角色。在工作中，使用过excel，wiki来进行接口文档的维护：
- wiki：缺点是维护起来工作量较大，费时较长，优点是体验较好、检索方便、支持多人协作、支持历史版本查看；
- excel：初始整理时还好，但在后续多人协作新增功能或调整接口时，维护接口文档就变得极不方便
然后了解到swagger2，可以以编程的方式方便的生成在线文档，这样在接口调整时，能够及时的变更接口文档，使接口文档的准确性更高，下面来看下如何在spring boot项目内整合swagger2.
配置swagger2
1、 添加依赖
<!-- swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
2、 添加基本配置
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors
.basePackage("com.onecoderspace.controller"))
.paths(PathSelectors.any()).build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("spring boot示例接口API")
.description("spring boot示例接口API")
.version("1.0").build();
}
}
- 通过@Configuration注解和@EnableSwagger2注解来启用Swagger2
- basePackage：配置Swagger2需要扫描的包
3、 使用示例
@Api(tags="用户管理",description="UserController")
@RestController
@RequestMapping("/user")
public class UserController {
@ApiOperation(value = "用户申请审核", notes = "用户申请审核")
@RequestMapping(value="/apply/audit",method=RequestMethod.GET)
public Return applyAudit() {
return Return.success();
}
@ApiOperation(value = "获取用户详细信息", notes = "根据ID查找用户")
@ApiImplicitParam(paramType = "query", name = "username", value = "用户名", required = true, dataType = "String")
@RequestMapping(value = "/get", method = RequestMethod.GET)
public User get(String username) {
return null;
}
@ApiOperation(value = "修改用户信息", notes = "修改用户信息")
@ApiImplicitParams({
@ApiImplicitParam(paramType = "query", name = "user", value = "用户实体", required = true, dataType = "user"),
@ApiImplicitParam(paramType = "query", name = "cname", value = "公司名称", required = true, dataType = "String") })
@RequestMapping(value = "/save", method = RequestMethod.POST)
public Return save(User user, String cname, String curl) {
return Return.success();
}
}
在线文档显示效果如下：
swagger2在线文档效果
- @Api:在类上添加注释，tags属性决定1处的内容，description决定2处的内容
- @ApiOperation：在方法上添加注释，用于说明某个请求url的作用，value属性决定3处的内容，notes决定5处的内容
- @ApiImplicitParam： 在方法上添加注释，用于说明某个请求参数的作用
- @ApiImplicitParams多个参数时使用该注解
- 在实体字段添加@ApiModelProperty(value="名称")，生成该字段的说明
4、 注意事项
- 如果系统加入shiro等权限框架，那么访问swagger-ui.html需要有ACTUATOR角色，这个不要忘了配置
- 对于实体参数的支持不太好，保存更新时如果字段不是很多，建议使用属性的方式替代使用实体
- swagger2是支持自定义页面的，如果觉得默认的样式不太适合，可以自定义前端页面，通过网络监控可以发现，所有数据是通过一个/v2/api-docs的请求获得的。
当接口较多时，swagger2也支持分组等配置，参考以下文档：
spring-boot-starter-swagger 1.3.0.RELEASE：新增对JSR-303的支持和host的配置
相关阅读：
swagger官网
Spring Boot中使用Swagger2构建强大的RESTful API文档
简化Swagger使用的自制Starter：spring-boot-starter-swagger，欢迎使用和吐槽
本人搭建好的spring boot web后端开发框架已上传至GitHub，欢迎吐槽！
https://github.com/q7322068/rest-base,已用于多个正式项目，当前可能因为版本问题不是很完善，后续持续优化，希望你能有所收获！
