spring boot实战之swagger2在线文档

对于接口服务来说接口文档极其重要，在团队配合和后续维护中占据重要角色。在工作中，使用过excel，wiki来进行接口文档的维护：

• wiki：缺点是维护起来工作量较大，费时较长，优点是体验较好、检索方便、支持多人协作、支持历史版本查看；
• excel：初始整理时还好，但在后续多人协作新增功能或调整接口时，维护接口文档就变得极不方便

然后了解到swagger2，可以以编程的方式方便的生成在线文档，这样在接口调整时，能够及时的变更接口文档，使接口文档的准确性更高，下面来看下如何在spring boot项目内整合swagger2.

配置swagger2

1、 添加依赖

    io.springfox
    springfox-swagger2
    2.7.0


    io.springfox
    springfox-swagger-ui
    2.7.0

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、 注意事项

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

本人搭建好的spring boot web后端开发框架已上传至GitHub，欢迎吐槽！
https://github.com/q7322068/rest-base,已用于多个正式项目，当前可能因为版本问题不是很完善，后续持续优化，希望你能有所收获！