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

码农架构

发布于 2021-10-12 11:02:29

5550

发布于 2021-10-12 11:02:29

导读：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的依赖

@Data
<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请求。

- END -

本文参与腾讯云自媒体分享计划，分享自微信公众号。

原始发表：2021-09-30，如有侵权请联系 cloudcommunity@tencent.com 删除

java

本文分享自码农架构微信公众号，前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体分享计划，欢迎热爱写作的你一起参与！

登录后参与评论

0 条评论

热度