Dataway 整合 Swagger2，让 API 管理更顺畅

2022-06-02 09:16:32

Dataway介绍

Dataway 是基于 DataQL 服务聚合能力，为应用提供的一个接口配置工具。使得使用者无需开发任何代码就配置一个满足需求的接口。整个接口配置、测试、冒烟、发布。一站式都通过 Dataway 提供的 UI 界面完成。UI 会以 Jar 包方式提供并集成到应用中并和应用共享同一个 http 端口，应用无需单独为 Dataway 开辟新的管理端口。

这种内嵌集成方式模式的优点是，可以使得大部分老项目都可以在无侵入的情况下直接应用 Dataway。进而改进老项目的迭代效率，大大减少企业项目研发成本。

Dataway 工具化的提供 DataQL 配置能力。这种研发模式的变革使得，相当多的需求开发场景只需要配置即可完成交付。从而避免了从数据存取到前端接口之间的一系列开发任务，例如：Mapper、BO、VO、DO、DAO、Service、Controller 统统不在需要。

研发管理中对于开发的 API 通常需要统一管理，在这一令领域比较常用的是 Swagger。它可以通过注解方式直接将开发的真实 API 形象的进行文档化，并且提供了一个 Swagger-UI 的界面来查阅。除此之外 Swagger-UI 上还可以发起模拟调用，这一功能是在是让开发人员非常舒心。

Dataway 的优势是在于，一些简单的接口或者聚合服务都可以不在需要开发。用过 Interface-UI 就可以配置和管理。在dataway 4.1.8 版本之前，研发管理上开发者需要在两个 UI 上切换来实现接口的测试和查阅。

新的 4.1.8 发布之后补充了这一短板，让 Dataway 上配置的接口可以直接产生 Swagger2 的API 文档。进一步的开发者可以将这个文档整合到应用自身的 API 文档中。统一管理和查阅、使用。

进一步的利用 Swagger 还可以通过 postman 来统一接口的调试、利用 yapi 还可以对接口进行批量的管理和验证。

接下来本文就会引导读者如何在一个 Spring 项目中让 Dataway 和 Swagger 整合起来。

第一步：引入Swagger

整合多个 Swagger 文档需要较高 Swagger 版本的支持，我们这里选用 2.7.0。

<!-- Swagger -->
<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>

第二步：引入Dataway

在 4.1.8 版本中 Dataway 支持了 Swagger 的文档输出，我们选用它。

<dependency>
    <groupId>net.hasor</groupId>
    <artifactId>hasor-spring</artifactId>
    <version>4.1.8</version>
</dependency>
<dependency>
    <groupId>net.hasor</groupId>
    <artifactId>hasor-dataway</artifactId>
    <version>4.1.8</version>
</dependency>

第三步：配置 Dataway 让其可以工作

@DimModule
@Component
public class ExampleModule implements SpringModule {
    @Autowired
    private DataSource dataSource = null; // 应用自己的数据源

    @Override
    public void loadModule(ApiBinder apiBinder) throws Throwable {
        // .DataSource form Spring boot into Hasor
        apiBinder.installModule(new JdbcModule(Level.Full, this.dataSource)); // 初始化Dataway 的数据源
        // .custom DataQL
        //
    }

    @Override
    public void onStart(AppContext appContext) throws Throwable {
        //
    }
}

更详细步骤可以参考《绝了！Dataway让Spring Boot不再需要Controller、Service、DAO、Mapper》https://my.oschina.net/ta8210/blog/3234639

第四步：整合 Dataway 的 Swagger 文档到一起

首先新建一个类，在应用中启用 Swagger

@EnableSwagger2
@Configuration()
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)//
                .apiInfo(apiInfo())//
                .select()//
                .apis(RequestHandlerSelectors.basePackage("net.example.hasor"))//
                .paths(PathSelectors.any())//
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()//
                .title("Spring Boot中使用Swagger2构建RESTful APIs")//
                .description("欢迎到我的GitHub：https://github.com/1610wang/")//
                .termsOfServiceUrl("https://github.com/1610wang/")//
                .contact("wxy").version("1.0")//
                .build();
    }
}

其次利用 Swagger 的接口整合两个文档到一起

@Component
@Primary
public class SwaggerProvider implements SwaggerResourcesProvider {
    @Override
    public List<SwaggerResource> get() {
        List<SwaggerResource> resources = new ArrayList<>();
        resources.add(swaggerResource("应用接口", "/v2/api-docs", "1.0"));
        resources.add(swaggerResource("Dataway接口", "/interface-ui/api/docs/swagger2.json", "1.0"));
        return resources;
    }

    private SwaggerResource swaggerResource(String name, String location, String version) {
        SwaggerResource swaggerResource = new SwaggerResource();
        swaggerResource.setName(name);
        swaggerResource.setLocation(location);
        swaggerResource.setSwaggerVersion(version);
        return swaggerResource;
    }
}