CN107391130B

CN107391130B - Api自动管理和sdk、文档自动生成方法

Info

Publication number: CN107391130B
Application number: CN201710554227.4A
Authority: CN
Inventors: 高云飞
Original assignee: Qianxun Spatial Intelligence Inc
Current assignee: Qianxun Spatial Intelligence Inc
Priority date: 2017-07-07
Filing date: 2017-07-07
Publication date: 2020-05-05
Anticipated expiration: 2037-07-07
Also published as: CN107391130A

Abstract

本发明提供了一种API自动管理方法，服务提供者引入组件，配置接口开放的参数和属性；服务提供者启动后端服务；在发布系统中配置提供服务的地址，从地址载入API元信息，API元信息处于Prepared列表中，API进入Prepared状态；从地址远程加载依赖信息；服务提供者检查拉取到的API的Prepared列表，确认需要发布的API元信息无误后提交，API进入Prototyped状态，等待发布；申请上线发布API，管理员审查无误后批准发布，API进入Published状态，正式对外服务。本发明降低了API发布、管理的人力成本和研发各语言版本SDK，重新编写文档的时间成本，提高技术人员工作效率。

Description

API自动管理和SDK、文档自动生成方法

技术领域

本发明涉及互联网技术领域，具体涉及一种API自动管理和SDK、文档自动生成方法。

背景技术

伴随着互联网时代的多元化发展，更多技术人员将精力投入到网络应用的开发上，致力于降低软件以及应用的开发门槛，产品服务化趋势和技术开放趋势日益显著。互联网产品服务化，基础设施能力服务化已经俨然成为大势所趋。然而对于许多中大型应用产品服务化的过程，必然伴随着许多APl(Application Programming Interface，应用程序编程接口，用于技术人员和软件程序交互的一种契约)的集成开放。快速的API版本迭代，大量的新增和消亡的API，管理海量API等，大量API发布后需要封装维护各语言版本的SDK(Software Development Kit，被软件工程师用于为特定的软件包、软件框架、硬件平台、操作系统等创建应用软件的开发工具的集合。其目的是封装一些底层复杂的程序逻辑，便于第三方开发者以自身熟悉的方式使用该软件)，需要重新编写API文档，这些工作都会带来频繁的维护需求和大量的人力成本。

目前，对于API发布技术的现有方案，为了具备通用性，现有技术通常有如下步骤：

1、部署后端服务。

2、手工编写符合发布规范的配置文件，包含但不仅限于参数、参数类型、服务参数，服务地址等等。

3、上传依赖包以及规范文件。

4、刷新配置文件，加载配置。

5、重新启动服务使新服务配置生效。

6、编写或修改SDK

7、编写新API文档。

这种方法通过手动编写某种符合规范或者约定的配置文件和上传依赖包、规范文件，以供OPEN API(开放API，也称开放平台。所谓OPEN API是服务型网站常见的一种应用，网站的服务商将互联网产品或者服务封装成一系列API开放出去，供第三方开发者使用，这种行为就叫做开放API，所开放的API就被称作OPEN API)识别新发布的API，并需要重启服务刷新网关侧程序信息。

这种方法每次发布后均需重新编写或者修改SDK代码，并发布使用。

但是，上述技术方案存在明显的缺陷，具体如下：

1、开发人员完成服务开发工作后，还需要进行配置工作，重复劳动降低效率。

2、在实际场景中，如果需要批量发布大量的API，需要手动编写大量配置文件，或者进行大量的人工配置，短时间难以实现。

3、该系统与后端交互需要借助特定的通用协议规范，例如json，protobuf方可工作，存在性能瓶颈。

4、如果存在多方API需要接入系统，可能需要进行引入多方依赖，导致频繁的维护升级和随之引发的各类问题。

5、反复更新维护SDK代码，浪费大量人力成本。

6、反复编写修改API文档，浪费大量人力成本。

发明内容

针对现有技术存在的问题，本发明提出了一种API自动管理方法，解决了以下技术问题：

1、提供通用组件，以标准格式编写服务接口，使开放人员简单方便的将配置步骤融入开发过程中，避免重复劳动。

2、拥有自动发现指定服务的API元信息，并实现远程加载的功能，使得发布1个API和发布1000个API并无任何区别，批量发布不再成为时间瓶颈。

3、拥有自动发现API依赖的功能，并实现远程加载，使得服务使用者(使用某种开放技术服务或者互联网产品的角色，可以是开发者，用户或者机构。)无需关心任何类元信息变化，自动变更依赖信息，无需人工维护。

4、无需借助特定外部第三方依赖，完全通过高效字节码序列化/反序列化完成，程序性能极高。

5、完成API自动更新后，会自动生成对应各语言版本SDK和相应API文档。

本发明采用的技术方案是：

一种API自动管理方法，包括：

服务提供者引入组件，配置接口开放的参数和属性；

服务提供者启动后端服务；

在发布系统中配置提供服务的地址，从所述地址远程加载API元信息，API元信息处于Prepared列表中，API进入Prepared状态；

从所述地址远程加载依赖信息；

服务提供者检查拉取到的API的Prepared列表，确认需要发布的API元信息无误后提交，API进入Prototyped状态，等待发布；

申请上线发布API，管理员审查无误后批准发布，API进入Published状态，正式对外服务。

进一步地，所述API自动管理方法还包括：申请下线API，API进入Deprecated状态，API停止服务并下线。

进一步地，所述API自动管理方法还包括：

禁用API元信息，关闭API服务功能，API进入Blocked状态，限制API访问；或者解禁API元信息，重新开放API服务功能，API进入Published状态，正式对外服务。

进一步地，如果API进入Blocked状态，申请下线API，API进入Deprecated状态，API停止服务并下线。

进一步地，所述服务提供者启动后端服务时，ScanUtil模块启动，扫描本地所有带标记的接口，组装API元信息，并收集依赖信息，分别存储于Dependency Provider和APIProvider。

进一步地API进入Prepared状态后，OPEN API通过API Fetcher向后端服务远程请求API元信息，并交由API Dealer处理解析，然后重载存储于API Store中。

一种SDK自动生成方法，存储于API Store中的API元信息，由SDKMaker抓取类元信息，自动生成各版本的SDK。

进一步地，所述SDK为C#、Java、Python或者C++。

一种文档自动生成方法，存储于API Store中的API元信息，由Doc Maker抓取类元信息，自动生成文档。

进一步地，所述文档为接口名、参数名、参数类型、接口描述、超时时间、指向地址、负载均衡策略、同步异步或者调用方式。

本发明的有益效果在于，降低API发布、管理的人力成本和研发各语言版本SDK，重新编写文档的时间成本，提高技术人员工作效率。

附图说明

图1是本发明API状态流转图。

图2是本发明流程泳道图。

图3是本发明系统结构图。

具体实施方式

本发明基于Java技术实现，适用于使用Java编写的任意系统及服务，涉及互联网信息技术领域，特别是各互联网开放或者开源技术服务平台，例如WSO2(WSO2是一个领先的开源SOA解决方案提供者)等。下文中，结合附图和实施例对本发明作进一步阐述。

图1是本发明API状态流转图，其中API状态定义如下：

Prepared(准备)：新建API处于Prepare List(列表)中，服务提供者(将某种互联网产品或者技术服务，以接口形式开放出来，提供给其他开发人员或者用户使用的人或者机构。此角色通常位于后端服务端。)进行信息确认。

Prototyped(原型)：确认提交，进入Prototyped状态，等待发布。

Published(发布)：服务提供者测试通过，网关通过审核的API进入Published状态，对外提供服务。

Deprecated(否决)：被标示为Deprecated的API，将会被停止服务并下线。

Blocked(访问限制)：API访问被限制，该状态主要起到保护服务的目的。

API操作定义如下：

Confirm：确认需要发布的API信息。

Publish：上线，申请发布状态。

Unpublish：申请下线API。

Block：禁用API信息，关闭其服务功能。

Unblock：解禁API信息，重新开放其功能。

图2是本发明流程泳道图，具体如下：

1、服务提供者引入组件，在代码中以Annotation(注释)形式，配置接口开放的参数和属性。

2、服务提供者启动后端服务。

3、在发布系统中配置提供服务的地址，从该地址远程加载API数据，此时API状态为Prepared。

4、从该地址远程加载依赖信息。

5、服务提供者在系统中检查拉取到的API的Prepared列表，确定自己需要发布的信息无误后提交，此时API处于Prototyped状态。

6、管理员(负责审查、审阅API开放是否合理、正确的审批人员，可以和服务提供者、服务使用者角色重合。)审查无误后批准发布，此时API处于Published状态，正式对外服务。

图3是本发明系统结构图，具体如下：

1、服务(service)启动时，即服务提供者启动后端服务时，ScanUtil(扫描功能)模块启动，负责扫描本地所有带有标记的接口，按照规范组装API元信息，并收集相关依赖信息，分别存储于Dependency Provider(依赖提供者)和API Provider(API提供者)。

2、服务侧准备完成后，OPEN API侧通过API Fetcher(API访问)向后端服务远程请求API元信息，并交由API Dealer(API处理)处理解析，然后重载存储于API Store(API存储)中，以供系统使用。

3、存储于API Store中的API信息，由SDK Maker(SDK生成)抓取类元信息，自动生成各版本SDK，包括但不仅限于C#，Java，Python，C++等程序语言。

4、存储于API Store中的API信息，由Doc Maker(文档生成)负责抓取类元信息，自动生成文档，包含内容：接口名，参数名，参数类型，接口描述，超时时间，指向地址，负载均衡策略，同步异步，调用方式等。

本发明中API信息的定义格式包含不限于swagger格式，json格式，xml格式，以及其他文本格式。

本发明远程加载的方式包含不限于RPC方式，RMI方式，以及其他基于TCP的方式。

本发明优选在Java语言环境。

本发明虽然已以较佳实施例公开如上，但其并不是用来限定本发明，任何本领域技术人员在不脱离本发明的精神和范围内，都可以利用上述揭示的方法和技术内容对本发明技术方案做出可能的变动和修改，因此，凡是未脱离本发明技术方案的内容，依据本发明的技术实质对以上实施例所作的任何简单修改、等同变化及修饰，均属于本发明技术方案的保护范围。

Claims

1.一种API自动管理方法，其特征在于，包括：

服务提供者引入组件，配置接口开放的参数和属性；

服务提供者启动后端服务；

从所述地址远程加载依赖信息；

2.如权利要求1所述的一种API自动管理方法，其特征在于，还包括：

申请下线API，API进入Deprecated状态，API停止服务并下线。

3.如权利要求1所述的一种API自动管理方法，其特征在于，还包括：

4.如权利要求3所述的一种API自动管理方法，其特征在于，如果API进入Blocked状态，申请下线API，API进入Deprecated状态，API停止服务并下线。

5.如权利要求1所述的一种API自动管理方法，其特征在于，所述服务提供者启动后端服务时，ScanUtil模块启动，扫描本地所有带标记的接口，组装API元信息，并收集依赖类元信息，分别存储依赖类元信息于Dependency Provider，存储API元信息于API Provider。

6.如权利要求5所述的一种API自动管理方法，其特征在于，API进入Prepared状态后，OPEN API通过API Fetcher向后端服务远程请求API元信息，并交由APIDealer处理解析，然后重载存储于API Store中。

7.一种SDK自动生成方法，其特征在于，包括如权利要求6所述的一种API自动管理方法，存储于API Store中的API元信息，由SDK Maker抓取类元信息，自动生成各版本的SDK。

8.如权利要求7所述的一种SDK自动生成方法，其特征在于，所述生成SDK的编程语言包括C#、Java、Python、PHP或者C++。

9.一种文档自动生成方法，其特征在于，包括如权利要求6所述的一种API自动管理方法，存储于API Store中的API元信息，由Doc Maker抓取类元信息，自动生成文本格式文档。

10.如权利要求9所述的一种文档自动生成方法，其特征在于，所述文档包括接口名、参数名、参数类型、接口描述、超时时间、指向地址、负载均衡策略、同步异步和调用方式之一种或几种。