CN101499002A - 一种生成接口文档的方法、系统和装置 - Google Patents

Abstract

本发明实施例公开了一种生成接口文档的方法，包括以下步骤：接收接口文档生成指令；根据所述接口文档生成指令，读取接口配置文件，获取当前接口配置信息；根据所述配置信息，为所述接口配置文件对应的接口生成接口文档。本发明实施例还公开了一种生成接口文档的系统和装置。通过应用本发明，保证了接口文档和系统实现的自动同步，从而大大减轻了技术人员编写接口文档的工作量。

Description

一种生成接口文档的方法、系统和装置

技术领域

本发明涉及系统技术领域，特别是涉及一种生成接口文档的方法、系统和装置。

背景技术

同一系统不同功能层之间的通信规则称为接口。

接口中可以声明属性、方法、事件和类型(Structure)，(但不能声明变量)，但是并不能设置这些成员的具体值，也就是说，只能定义，不能给它里面定义的东西赋值。

而对接口的配置进行描述的文件，就是接口配置文件，在现有技术中，工作人员需要通过读取接口配置文件，并根据接口配置文件中的信息，手工编写接口文档。

由于文档和系统实现是分离的，所以在系统接口发生改变，接口配置文件更新后，并不能第一时间生成新的接口文档，而是需要技术人员发现接口变更，而去读取接口配置文件，修改接口文档，从而使接口文档的更新完全依赖于技术人员主动对接口信息变更的发现，使接口文档的更新往往滞后，出现接口文档和系统实现不一致的问题，并可能由于技术人员的人为失误，出现接口文档撰写错误，准确率降低的后果，影响系统维护和正常工作。

因此，迫切需要提供一种新技术，是接口文档的更新或新接口文档的生成自动化，在系统接口发生变化后，自动生成新的接口文档，实现文档内容和系统实现的同步。

发明内容

本发明实施例要解决的问题是提供一种生成接口文档的方法、系统和装置，实现了接口文档和系统实现的自动同步，从而大大减轻了技术人员编写接口文档的工作量，并提高接口文档信息的准确性。

为达到上述目的，本发明实施例一方面提出一种生成接口文档的方法，包括以下步骤：

接收接口文档生成指令；

根据所述接口文档生成指令，读取接口配置文件，获取当前接口配置信息；

根据所述配置信息，为所述接口配置文件对应的接口生成接口文档。

其中，所述接口文档生成指令，具体为：

根据接口文件的更新频率，设定自动发送所述接口文件生成指令的周期；

根据所述周期，发送所述接口文件生成指令。

其中，所述接口文档生成指令，具体为：

实时检测系统更新信息；

当检测到所述系统的接口发生更改时，自动发送接口文件生成指令。

其中，所述生成接口文档之后还包括：

输出所述接口文档，并覆盖所述接口的原有接口文档。

另一方面，本发明实施例还提供了一种生成接口文档的系统，其特征在于，包括：

任务调度器，用于发送接口文档生成指令；

文档生成器，用于根据所述任务调度器发送的接口文档生成指令，读取当前接口的配置文档，生成所述接口的接口文档。

另一方面，本发明实施例还提供了一种任务调度器，包括：

模式设定模块，用于设置接口文档生成指令的发送模式；

指令发送模块，用于根据所述模式设定模块所设定的接口文档生成指令发送模式将接口文档生成指令发送给所述文档生成器。

其中，所述模式设定模块包括：

发送周期设定子模块，用于根据接口文件的更新频率要求，设定自动发送所述接口文件生成指令的周期。

其中，所述模式设定模块包括：

系统检测子模块，用于实时检测系统更新信息。

另一方面，本发明实施例还提供了一种文档生成器，包括：

指令接收模块，用于接收所述任务调度器发送的接口文档生成指令；

文件分析模块，用于根据所述指令接收模块接收的接口文档生成指令，读取接口配置文件，获得所述接口的配置信息；

文档输出模块，用于根据所述文件读取模块所获取的接口配置信息，生成所述接口的接口文档，并输出所述接口文档，覆盖所述接口的原有接口文档。

其中，所述文件分析模块包括：

文件读取子模块，用于读取所述接口配置文件；

信息分析子模块，用于根据所述文件读取子模块所读取的接口配置文件，获得所述接口的配置信息。

其中，所述文档输出模块包括：

文档生成子模块，用于根据所述文件读取模块所获取的接口配置信息，生成所述接口的接口文档；

文件输出子模块，用于输出所述文档生成子模块所生成的接口文档，并覆盖所述接口的原有接口文档。

本发明实施例的技术方案具有以下优点，因为采用了接口文档自动生成的方法，由系统自动生成接口文档，不再需要人共参与，达到了接口文档和系统实现的自动同步，提高文档描述的准确性，并进而降低技术人员编写文档工作量的效果。

附图说明

图1为本发明实施例一，一种基于周期发送接口文档生成指令的文档生成方法的流程示意图；

图2为本发明实施例二，一种基于系统接口实时检测的文档生成方法的流程示意图；

图3为本发明实施例三，一种生成接口文档的系统的结构示意图；

图4为本发明实施例四，一种基于周期发送接口文档生成指令的任务调度器的结构示意图；

图5为本发明实施例五，一种基于系统接口实时检测的任务调度器的结构示意图；

图6为本发明实施例六，一种文档生成器的结构示意图。

具体实施方式

本发明实施例提供了一种生成接口文档的方法、系统和装置，实现了接口文档和系统实现的自动同步，从而大大减轻了技术人员编写接口文档的工作量。

下面结合附图和实施例，对本发明的具体实施方式作进一步详细描述：

如图1所示，为本发明实施例一，一种基于周期发送接口文档生成指令的文档生成方法，包括以下步骤：

步骤S101、根据周期模式设定，发送接口文档生成指令。

接口文档生成指令的发送周期根据系统接口更新频率要求进行设定，如每小时、每天或其他周期设定。

更新频率可以进行人工设定，具体根据系统接口的实际变更情况进行设定，也可以使用程序进行控制，如：QUARTZ API，Linux操作系统自带的crontab等。

步骤S102、接收按照上述设定模式发出的接口文档生成指令，并获取需要生成新接口文档的接口标识。

可以设定为根据接口文件生成指令具体针对某一接口进行接口文档生成操作，也可设定为对所有接口进行接口文档生成操作，即对所有系统接口进行接口文档更新。

步骤S103、读取相应接口的接口配置文件，得到该接口的配置信息。

接口配置文件，是描述接口的配置文件。该文件用于接口的实现。结构类似于：

<exterfaces>

   <exterfaces>

       <field name＝＂user_id＂field＝＂userId＂desc＝＂用户ID＂accessable＝＂true＂/>

       <field name＝＂email＂field＝＂email＂desc＝＂用户Email＂accessable＝＂true＂/>

   <exterfaces>

<exterfaces>

根据上述的接口配置文件，分析得到对应接口的配置信息，如：接口名、接口类型、字符长度等。

步骤S104、根据配置信息，生成该接口的接口文档。

生成接口文档的操作可以通过程序自动完成，如：Java使用itext生成.pdf文件，Java使用jxl生成Excel文件等。

步骤S105、输出接口文档，并覆盖对应接口的原有接口文档。

如图2所示，为本发明实施例二，一种基于系统接口实时检测的文档生成方法，包括以下步骤：

步骤S201、实时检测系统的接口信息，检测系统接口信息是否发生变更。

当发现系统接口信息变更时，转入步骤S202。

步骤S202、发送接口文档生成指令。

步骤S203、接收上述接口文档生成指令，并获取需要生成新接口文档的接口标识。

步骤S204、读取相应接口的接口配置文件，得到该接口的配置信息。

步骤S205、根据配置信息，生成该接口的接口文档。

生成接口文档的操作可以通过程序自动完成，如：Java使用itext生成.pdf文件，Java使用jxl生成Excel文件等。

步骤S206、输出接口文档，并覆盖对应接口的原有接口文档。

如图3所示，为本发明实施例三，一种生成接口文档的系统，包括：

任务调度器1，用于发送接口文档生成指令；

文档生成器2，用于根据所述任务调度器1发送的接口文档生成指令，读取当前接口的配置文档，生成所述接口的接口文档。

如图4所示，为本发明实施例四，一种基于周期发送接口文档生成指令的任务调度器1，包括：

模式设定模块11，用于设置接口文档生成指令的发送模式；

指令发送模块12，用于根据所述模式设定模块11所设定的接口文档生成指令发送模式将接口文档生成指令发送给所述文档生成器2。

其中，所述模式设定模块11包括：

发送周期设定子模块111，用于根据接口文件的更新频率要求，设定自动发送所述接口文件生成指令的周期。

如图5所示，为本发明实施例四，一种基于系统接口实时检测的任务调度器1，包括本发明实施例四中的模式设定模块11和指令发送模块12。

其中，所述模式设定模块11包括：

系统检测子模块112，用于实时检测系统更新信息。

如图6所示，为本发明实施例五，一种文档生成器2，包括：

指令接收模块21，用于接收所述任务调度器1发送的接口文档生成指令；

文件分析模块22，用于根据所述指令接收模块21接收的接口文档生成指令，读取接口配置文件，获得所述接口的配置信息；

文档输出模块23，用于根据所述文件读取模块22所获取的接口配置信息，生成所述接口的接口文档，并输出所述接口文档，覆盖所述接口的原有接口文档。

其中，所述文件分析模块22包括：

文件读取子模块221，用于读取所述接口配置文件；

信息分析子模块222，用于根据所述文件读取子模块221所读取的接口配置文件，获得所述接口的配置信息。

其中，所述文档输出模块包括：

文档生成子模块231，用于根据所述文件分析模块22所获取的接口配置信息，生成所述接口的接口文档；

文件输出子模块232，用于输出所述文档生成子模块231所生成的接口文档，并覆盖所述接口的原有接口文档。

本发明实施例的技术方案具有以下优点，因为采用了接口文档自动生成的方法，由系统自动生成接口文档，不再需要人共参与，达到了接口文档和系统实现的自动同步，提高文档描述的准确性，并进而降低技术人员编写文档工作量的效果。

通过以上的实施方式的描述，本领域的技术人员可以清楚地了解到本发明可借助软件加必需的通用硬件平台的方式来实现，当然也可以通过硬件，但很多情况下前者是更佳的实施方式。基于这样的理解，本发明的技术方案本质上或者说对现有技术做出贡献的部分可以以软件产品的形式体现出来，该计算机软件产品存储在一个存储介质中，包括若干指令用以使得一台终端设备(可以是手机，个人计算机，服务器，或者网络设备等)执行本发明各个实施例所述的方法。

以上所述仅是本发明的优选实施方式，应当指出，对于本技术领域的普通技术人员来说，在不脱离本发明原理的前提下，还可以做出若干改进和润饰，这些改进和润饰也应视本发明的保护范围。

Claims (11)

1、一种生成接口文档的方法，其特征在于，包括以下步骤：

接收接口文档生成指令；

根据所述接口文档生成指令，读取接口配置文件，获取当前接口配置信息；

根据所述配置信息，为所述接口配置文件对应的接口生成接口文档。

2、如权利要求1所述自动生成接口文档的方法，其特征在于，所述接口文档生成指令，具体为：

根据接口文件的更新频率，设定自动发送所述接口文件生成指令的周期；

根据所述周期，发送所述接口文件生成指令。

3、如权利要求1所述自动生成接口文档的方法，其特征在于，所述接口文档生成指令，具体为：

实时检测系统更新信息；

当检测到所述系统的接口发生更改时，自动发送接口文件生成指令。

4、如权利要求1所述自动生成接口文档的方法，其特征在于，所述生成接口文档之后还包括：

输出所述接口文档，并覆盖所述接口的原有接口文档。

5、一种生成接口文档的系统，其特征在于，包括任务调度器和文档生成器：

所述任务调度器，用于发送接口文档生成指令；

所述文档生成器，用于根据所述任务调度器发送的接口文档生成指令，读取当前接口的配置文档，生成所述接口的接口文档。

6、一种任务调度器，其特征在于，包括：

模式设定模块，用于设置接口文档生成指令的发送模式；

指令发送模块，用于根据所述模式设定模块所设定的接口文档生成指令发送模式将接口文档生成指令发送给所述文档生成器。

7、如权利要求6所述的任务调度器，其特征在于，所述模式设定模块包括：

发送周期设定子模块，用于根据接口文件的更新频率要求，设定自动发送所述接口文件生成指令的周期。

8、如权利要求6所述的任务调度器，其特征在于，所述模式设定模块包括：

系统检测子模块，用于实时检测系统更新信息。

9、一种文档生成器，其特征在于，包括：

指令接收模块，用于接收所述任务调度器发送的接口文档生成指令；

文件分析模块，用于根据所述指令接收模块接收的接口文档生成指令，读取接口配置文件，获得所述接口的配置信息；

文档输出模块，用于根据所述文件读取模块所获取的接口配置信息，生成所述接口的接口文档，并输出所述接口文档，覆盖所述接口的原有接口文档。

10、如权利要求9所述的文档生成器，其特征在于，所述文件分析模块包括：

文件读取子模块，用于读取所述接口配置文件；

信息分析子模块，用于根据所述文件读取子模块所读取的接口配置文件，获得所述接口的配置信息。

11、如权利要求9所述的文档生成器，其特征在于，所述文档输出模块包括：

文档生成子模块，用于根据所述文件读取模块所获取的接口配置信息，生成所述接口的接口文档；

文件输出子模块，用于输出所述文档生成子模块所生成的接口文档，并覆盖所述接口的原有接口文档。

Images