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

原创
09/30 13:55
阅读数 152

由于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的依赖

<dependency>
    <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
</dependency>

目前个人使用版本

<swagger.version>2.9.2</swagger.version>

二、创建Swagger2配置类

图片

/**
 * swagger配置
 * 前端通过/swagger-ui.html访问得到地址
 */
@ConditionalOnProperty(value = "kmss.auth.swaggerEnable", havingValue = "true")
@ConditionalOnClass(EnableSwagger2.class)
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 动态产生Docket分组信息
     *
     * @return
     */
    @Autowired
    public void dynamicConfiguration(ApplicationContext applicationContext) {
        ConfigurableApplicationContext context = (ConfigurableApplicationContext) applicationContext;
        DefaultListableBeanFactory beanFactory = (DefaultListableBeanFactory) context.getBeanFactory();
        ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder()
            .title("标题//")
            .description("描述//")
            .version("版本//")
            .license("许可证//");
        Collection<MetaModule> 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 + "/**"),
                            PathSelectors.ant(NamingConstant.PATH_PREFIX_API + "/**")))
                    .build();
            beanFactory.registerSingleton(StringHelper.join("swagger-", moduleName), docket);
        }
    }
 
    /**
     * 模块路径
     *
     * @param moduleName
     * @return
     */
    private Predicate<RequestHandler> 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<MetaModule> modules = LocalMetaContextHolder.get().getModules().values();

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

三、添加文档内容

图片

图片

图片

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

图片

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

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

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

    

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

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

展开阅读全文
打赏
0
0 收藏
分享
加载中
更多评论
打赏
0 评论
0 收藏
0
分享
返回顶部
顶部