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

原创
05/28 13:41
阅读数 4.1K

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("欢迎到我的项目:https://gitee.com/zycgit/hasor")//
                .termsOfServiceUrl("https://gitee.com/zycgit/hasor")//
                .contact("zyc").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;
    }
}

最后启动应用,首先输入 Swagger-UI 看到的是应用自身的 API 信息。由于我们是一个空项目,这里没有任何显示。

接着我们切换 Swagger 的文档

展开 Default 就可以看到我们配置的接口了。

在切换到 Dataway 的UI 中对比一下是不是所有已经发布的 API 都已经在 Swagger 中展示出来了。

第五步:用 SwaggerUI 测试Dataway 接口

点开其中一个 Dataway 接口我们尝试输入必要的参数测试一下。

返回结果

注意事项

这是一项新的功能,对于 4.1.8 之前已经在使用的老接口。您需要重新发布一次接口。

否则的话,Dataway 并没有记录接口的入参和出参格式,因此也就无法生成一个准确的 Swagger 的接口入参和出参信息。

展开阅读全文
打赏
0
3 收藏
分享
加载中
大佬,只能在/interface-ui/api 下面才能看到文档吗,改成其他的就不能了
06/06 14:56
回复
举报
哈库纳博主
一定是在 ui 下面才可以,你可以把 dataway ui 整体的 路径换掉。这时候 swagger2.json 的地址也会跟随变化。
06/06 17:39
回复
举报
优秀。通常企业也是用的swagger。这样API的流量更方便更通用。最好支持类似@ApiOperation @ApiModelProperty的参数,方法注解。还有方法的分组
05/29 09:41
回复
举报
哈库纳博主
不需要参数注解,Dataway 会自动根据入参/出参的 json 格式来推断并生成 Swagger 数据模型。 分组已经有一个简单的根据 api 路径分组能力了。
05/29 13:03
回复
举报
数据模型是有了,但是参数的描述呢
05/29 13:30
回复
举报
补充下,如果几百个接口。几十个参数时,是不是有个参数描述会对调用者会更清晰:)
05/29 13:32
回复
举报
哈库纳博主
4.1.9 中正在考虑加入这个能力。
06/06 17:38
回复
举报
更多评论
打赏
7 评论
3 收藏
0
分享
返回顶部
顶部