[置顶] spring boot项目实战：swagger2在线文档

对于接口服务来说接口文档极其重要，在团队配合和后续维护中占据重要角色。在工作中，使用过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)

4000
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();
}
}

在线文档显示效果如下：



- @Api:在类上添加注释，tags属性决定1处的内容，description决定2处的内容

- @ApiOperation：在方法上添加注释，用于说明某个请求url的作用，value属性决定3处的内容，notes决定5处的内容

- @ApiImplicitParam： 在方法上添加注释，用于说明某个请求参数的作用

- @ApiImplicitParams多个参数时使用该注解

- 在实体字段添加@ApiModelProperty(value=”名称”)，生成该字段的说明

4、 注意事项

1. 如果系统加入shiro等权限框架，那么访问swagger-ui.html需要有ACTUATOR角色，这个不要忘了配置

2. 对于实体参数的支持不太好，保存更新时如果字段不是很多，建议使用属性的方式替代使用实体

3. 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，欢迎使用和吐槽

个人博客，欢迎来访！

足迹|成长之路