Spring Boot集成Swagger2构建强大的RESTful API文档

导读：Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。

由于Spring Boot能够快速开发、便捷部署等特性，相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因，这些终端会共用很多底层业务逻辑，因此我们会抽象出这样一层来同时服务于多个移动端或者Web前端。

本文将介绍RESTful API的重磅好伙伴Swagger2，它可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。具体效果如下图所示：

一、添加Swagger2依赖

在pom.xml中加入Swagger2的依赖

    io.springfox
     springfox-swagger2


     io.springfox
     springfox-swagger-ui

目前个人使用版本

2.9.2

二、创建Swagger2配置类

@ConditionalOnProperty(value = "kmss.auth.swaggerEnable", havingValue = "true")
@ConditionalOnClass(EnableSwagger2.class)
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    @Autowired
    public void dynamicConfiguration(ApplicationContext applicationContext) {
        ConfigurableApplicationContext context = (ConfigurableApplicationContext) applicationContext;
        DefaultListableBeanFactory beanFactory = (DefaultListableBeanFactory) context.getBeanFactory();
        ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder()
            .title("标题//")
            .description("描述//")
            .version("版本//")
            .license("许可证//");
        Collection modules = LocalmetaContextHolder.get().getModules().values();
        for (metaModule module : modules) {
            String moduleName = module.getName();
            Docket docket = new Docket(documentationType.SWAGGER_2)
                    .groupName(moduleName)
                    .apiInfo(apiInfoBuilder.title(module.getLabel()).build())
                    .select()
                    .apis(genSubPackage(moduleName))
                    .paths(Predicates.or(PathSelectors.ant(NamingConstant.PATH_PREFIX_DATA + "
    private Predicate genSubPackage(String moduleName) {
        return RequestHandlerSelectors.basePackage(NamingConstant.base_PACKAGE
                + NamingConstant.DOT
                + moduleName.replace(NamingConstant.STRIKE, NamingConstant.DOT));
    }
}

核心配置

• ApiInfoBuilderAPI的基础信息声明，包含标题、版本、描述、服务地址等配置

• DocketAPI接口分组标识、ApiInfoBuilder基础信息、api服务路径、api请求路径等配置

附：为什么通过Docket分组服务信息？

作为微服务架构，多个服务拆分部署算是家常便饭！但是对于整个系统api要统一管理。

Collection modules = LocalmetaContextHolder.get().getModules().values();

获取所有应用的配置信息便于通过Docket进行分组管理。

三、添加文档内容

对于文档补充还有更多适用的声明，可以按照官方文档参考适用

完成上述代码添加上，启动Spring Boot程序，访问

http://localhost:8080/swagger-ui.html

就能看到前文所展示的RESTful API的页面。我们可以再点开具体的API请求。

 专注于高质量 技术文章原创分享与交流，拒绝水文、软文。

首发：Spring Boot中使用Swagger2构建强大的RESTful API文档