WO2025112699A1 - 接口文档生成方法、装置、设备和存储介质 - Google Patents

接口文档生成方法、装置、设备和存储介质 Download PDF

Info

Publication number
WO2025112699A1
WO2025112699A1 PCT/CN2024/113797 CN2024113797W WO2025112699A1 WO 2025112699 A1 WO2025112699 A1 WO 2025112699A1 CN 2024113797 W CN2024113797 W CN 2024113797W WO 2025112699 A1 WO2025112699 A1 WO 2025112699A1
Authority
WO
WIPO (PCT)
Prior art keywords
interface document
interface
annotation information
document generation
target application
Prior art date
Legal status (The legal status is an assumption and is not a legal conclusion. Google has not performed a legal analysis and makes no representation as to the accuracy of the status listed.)
Pending
Application number
PCT/CN2024/113797
Other languages
English (en)
French (fr)
Inventor
陈安林
李司坤
刘健
普加红
马俊
Current Assignee (The listed assignees may be inaccurate. Google has not performed a legal analysis and makes no representation or warranty as to the accuracy of the list.)
China Mobile Communications Group Co Ltd
China Mobile IoT Co Ltd
Original Assignee
China Mobile Communications Group Co Ltd
China Mobile IoT Co Ltd
Priority date (The priority date is an assumption and is not a legal conclusion. Google has not performed a legal analysis and makes no representation as to the accuracy of the date listed.)
Filing date
Publication date
Application filed by China Mobile Communications Group Co Ltd, China Mobile IoT Co Ltd filed Critical China Mobile Communications Group Co Ltd
Publication of WO2025112699A1 publication Critical patent/WO2025112699A1/zh
Anticipated expiration legal-status Critical
Pending legal-status Critical Current

Links

Classifications

    • G—PHYSICS
    • G06—COMPUTING OR CALCULATING; COUNTING
    • G06F—ELECTRIC DIGITAL DATA PROCESSING
    • G06F8/00—Arrangements for software engineering
    • G06F8/70—Software maintenance or management
    • G06F8/73—Program documentation
    • G—PHYSICS
    • G06—COMPUTING OR CALCULATING; COUNTING
    • G06F—ELECTRIC DIGITAL DATA PROCESSING
    • G06F8/00—Arrangements for software engineering
    • G06F8/40—Transformation of program code
    • G06F8/41—Compilation
    • G06F8/42—Syntactic analysis
    • G06F8/427—Parsing
    • G—PHYSICS
    • G06—COMPUTING OR CALCULATING; COUNTING
    • G06F—ELECTRIC DIGITAL DATA PROCESSING
    • G06F8/00—Arrangements for software engineering
    • G06F8/60—Software deployment
    • G06F8/65—Updates

Definitions

  • the present disclosure relates to the field of network security, and in particular to an interface document generation method, device, equipment and storage medium.
  • the swagger component mainly includes program logic, swagger annotation tags, and swagger front-end static resources.
  • Swagger is a framework that can be used to design, build, document, and execute APIs.
  • the usage of the swagger component requires the current project to introduce the component package, that is, to package the swagger component into the current project package, as shown in Figure 1, the application packages of the production environment and the test environment at this time contain the swagger component.
  • the packaged swagger component will be launched together with the software after it is launched. Since the program developer of the swagger component needs to use standardized swagger annotations in the code during development, other codes or designs need to be changed accordingly to adapt to the new component, which is not conducive to code reuse and has a certain degree of invasiveness.
  • the swagger component will exist in the application from development and testing to production along with the software development life cycle. Although the production environment swagger can disable the configuration of the front-end page, judging from the security vulnerabilities of historical versions, many security issues have occurred and there are security vulnerabilities.
  • the purpose of the embodiments of the present disclosure is to provide an interface document generation method, apparatus, device and storage medium, which do not require the use of standardized special annotations, are completely non-invasive to the program, do not require the introduction of swagger components in project engineering, and swagger components will not run through the entire life cycle of software development, thereby improving system security.
  • the present disclosure provides a method for generating an interface document, including:
  • the generating of the interface document according to the parameter annotation information includes:
  • the parameter annotation information is parsed out from the object list, and the parsed parameter annotation information is rendered into a static resource to generate an interface document.
  • scanning the target application code includes:
  • the target application code is scanned using a code extraction tool through the interface file path specified in the configuration file.
  • the code extraction tool includes Javadoc in the jdk toolkit.
  • the target application code is annotated in advance using Java annotation standards.
  • the preset file is a pom file or a gradle file.
  • the static resource contains an interface document configuration template; the rendering of the parsed parameter annotation information into the static resource includes:
  • the parameter annotation information obtained by parsing is rendered into the interface document configuration template of the static resource.
  • an interface document generation device including:
  • a target application code packaging module is used to obtain the target application code in the target project engineering; wherein the target project engineering is a project engineering to be referenced by a preset file;
  • a parameter annotation information acquisition module is used to scan the target application code to obtain parameter annotation information containing interface information
  • the interface document generation module is used to generate an interface document according to the parameter annotation information.
  • an embodiment of the present disclosure also provides an interface document generation device, including a processor, a memory, and a computer program stored in the memory and configured to be executed by the processor, and when the processor executes the computer program, it implements the interface document generation method described in any of the above embodiments.
  • an embodiment of the present disclosure further provides a computer-readable storage medium, wherein the computer-readable storage medium includes a stored computer program, wherein when the computer program is running, the device where the computer-readable storage medium is located is controlled to execute the interface document generation method as described in any of the above embodiments.
  • the interface document generation method, device, equipment and storage medium disclosed in the present disclosure in the process of generating interface documents, first obtain the target application code in the target project engineering; wherein, this target project engineering is a project engineering to be referenced by a preset file, thereby realizing that the interface document generation device reversely references the engineering to be developed or tested and packages it, rather than the engineering to be developed referencing the component package, and there is no need to modify the target application code except for writing the interface annotation information in accordance with regulations; after packaging the target application code, the target application code is scanned to obtain parameter annotation information containing interface information, and an interface document is generated according to the parameter annotation information.
  • this target project engineering is a project engineering to be referenced by a preset file, thereby realizing that the interface document generation device reversely references the engineering to be developed or tested and packages it, rather than the engineering to be developed referencing the component package, and there is no need to modify the target application code except for writing the interface annotation information in accordance with regulations; after packaging the target application code, the target application code is
  • FIG1 is a schematic diagram of using a swagger component to generate an interface document provided by the prior art
  • FIG2 is a flow chart of a method for generating an interface document provided by an embodiment of the present disclosure
  • FIG3 is a schematic diagram of an interface document generation method provided by an embodiment of the present disclosure.
  • FIG4 is a structural block diagram of an interface document generating device provided by an embodiment of the present disclosure.
  • FIG5 is a structural block diagram of an interface document generating device provided in an embodiment of the present disclosure.
  • FIG. 2 is a flow chart of an interface document generation method provided by an embodiment of the present disclosure.
  • the interface document generation method is applied in a test development environment and is implemented by a document generation device.
  • the interface document generation method includes:
  • the application software in the production environment contains several project projects, and the target project project is a project project that needs to be tested and debugged in the test development environment.
  • the target application code in the target project project is first obtained; wherein, this target project project is a project project that needs to be referenced by the preset file in the interface document generation device in the test development environment, thereby enabling the interface document generation device to reversely reference the project project to be developed or tested and package it, rather than the project project to be developed referencing the component package, and there is no need to modify the target application code of the project project except for writing the interface comment information in accordance with regulations.
  • the target application code After packaging the target application code, the target application code is scanned to obtain parameter comment information containing interface information, and the interface is generated according to the parameter comment information.
  • Document the interface document is an online interface document, such as a web page generated and displayed on a browser page to display and debug the online interface document, and testers can perform debugging.
  • the application package A and the application package B in the production environment are the target application codes. Since there is no need to introduce the swagger component in the project engineering, the swagger component will not run through the entire life cycle of the software development, and there will be no swagger component or any other component that can generate interface documents in the production environment. In addition, after the tester completes the debugging and testing, when the software is launched, only the business program to be launched is packaged in the production environment.
  • the mvn package is used to specify the business program to be packaged and launched, and the document generation device that performs the above steps S1 to S3 in the test development environment is not packaged, that is, the test page is fundamentally avoided from entering the production environment.
  • the tester needs to test the software, it only needs to expose the IP address and port of the document generation device to the tester, and the tester can find the document generation device according to the IP address and port, and perform the development test of the corresponding software in the development environment.
  • the address and port of the document generation device can remain unchanged in the test environment. Even in the containerized environment, after packaging by reverse reference, only the IP address and port of the document generation device need to be exposed to simulate the call of the interface online.
  • the target application code is pre-annotated using the Java annotation specification.
  • Developers write comments, rather than annotations, for the interfaces and parameter object fields to be exposed by the software in accordance with the Java annotation specification.
  • Annotations usually require custom tags to be intrusively added to the target system code, while comments are in the Java file comment format and are non-intrusive. Therefore, comments are used in the embodiments of the present disclosure.
  • the text used to explain the program is a comment.
  • the comment types in Java include single-line comments, multi-line comments, and document comments (Java-specific). Comments are a good programming habit that a programmer must have. First, organize your thoughts through comments, and then use code to reflect them. For single-line and multi-line comments, the commented text will not be interpreted and executed by the JVM (Java Virtual Machine).
  • the comment content can be parsed by the Javadoc tool provided by JDK to generate a set of program descriptions in the form of web page files. Documentation.
  • the preset file is a pom file or a gradle file
  • the document generation device contains a pom file or a gradle file
  • the project to be developed or tested is referenced in the pom file or the gradle file, and then packaged.
  • pom is the abbreviation of Project Object Model
  • the pom file mainly describes the maven coordinates of the project.
  • the file is used to manage: source code, configuration files, developer information and roles, issue tracking system, organizational information, project authorization, project URL, project dependencies, etc. Therefore, the pom file is a project-level configuration file.
  • the gradle file is a script created by the gradle tool, which is a tool used to help teams build and deliver software.
  • Gradle is a build tool that is used to help testers build projects.
  • the build includes compilation, packaging and other processes.
  • Testers can specify build rules for gradle, and then the gradle file will automatically build the project according to the tester's "command".
  • the gradle file is also a project-level configuration file.
  • the Java annotation specification is used to write annotations for the interface and parameter object fields to be exposed by the software, without the need to use the standard special swagger annotations, which is completely non-invasive to the program.
  • the target application code is scanned using a code extraction tool through the interface file path specified in the configuration file.
  • the test development environment needs to install jdk (java development kit), and the code extraction tool is Javadoc in the jdk toolkit.
  • the code to be scanned is indexed by the interface file path specified in the configuration file.
  • the device uses the configuration file to scan the interface file range.
  • the parameter annotation information containing the interface information in the specified range is extracted through $Java_HOME/lib/tools.jar in Javadoc in the jdk toolkit.
  • the interface is annotated as follows using the Java annotation specification (this annotation is the parameter annotation information):
  • *@param n is the first parameter received, the starting point of the range
  • the interface information includes but is not limited to interface type, interface name, request parameters, return parameters, etc.
  • the interface type and name include: 1 interface based on http protocol, specifically divided into get, post, put, delete type interfaces; 2 interface based on web service, specifically there are the following 3 types: SOAP (simple object access protocol, simple object access protocol) type, RMI (Remote Method Invocation, remote method call) type and RPC (Remote Procedure Calls, remote procedure call) type; if the request parameter is http request, the return parameter is the parameter corresponding to the http request.
  • SOAP simple object access protocol
  • RMI Remote Method Invocation, remote method call
  • RPC Remote Procedure Calls, remote procedure call
  • step S3 generating an interface document according to the parameter annotation information includes:
  • S22 parse the parameter annotation information in the object list, and render the parameter annotation information obtained by parsing into static resources to generate an interface document.
  • Java is an object-oriented programming language.
  • an object is an entity of a class, and an object implements the encapsulation of some related data and algorithms.
  • the interface document generation device writes the parameter annotation information into the object list in the Java memory to encapsulate the parameter annotation information.
  • the object list contains several objects, and one object can encapsulate a parameter annotation information (i.e., the interface information corresponding to an interface).
  • the interface document generation device parses the parameter annotation information from the Java object list, and renders the parsed parameter annotation information into static resources. Only after the data is rendered into static resources can html and other resources that can be recognized by the web browser be generated, thereby generating a reference to the interface document.
  • the static resource contains an interface document configuration template; then, rendering the parsed parameter annotation information into the static resource includes:
  • the parameter annotation information obtained by parsing is rendered into the interface document configuration template of the static resource.
  • the interface document configuration template includes at least information such as interface name, interface call path, interface input parameter information, interface output parameter information, and interface request method.
  • the interface document generation method disclosed in the present disclosure in the process of generating the interface document, first obtains the target application code in the target project engineering; wherein, this target project engineering is a project engineering to be referenced by a preset file, thereby realizing that the interface document generation device reversely references the engineering to be developed or tested and packages it, rather than the engineering to be developed referencing the component package, and there is no need to modify the target application code except for writing the interface annotation information in accordance with the regulations; after packaging the target application code, the target application code is scanned to obtain parameter annotation information containing interface information, and an interface document is generated according to the parameter annotation information.
  • this target project engineering is a project engineering to be referenced by a preset file, thereby realizing that the interface document generation device reversely references the engineering to be developed or tested and packages it, rather than the engineering to be developed referencing the component package, and there is no need to modify the target application code except for writing the interface annotation information in accordance with the regulations; after packaging the target application code, the target application code is scanned to
  • FIG. 4 is a structural block diagram of an interface document generating device 100 provided in an embodiment of the present disclosure, wherein the interface document generating device 100 includes:
  • the target application code packaging module 11 is used to obtain the target application code in the target project engineering; wherein the target project engineering is the project engineering to be referenced by the preset file;
  • a parameter annotation information acquisition module 12 is used to scan the target application code to obtain parameter annotation information containing interface information
  • the interface document generating module 13 is used to generate an interface document according to the parameter annotation information.
  • the interface document generation module 13 includes:
  • An object writing unit used for writing the parameter annotation information into an object list in a memory
  • a parsing unit used for parsing the parameter annotation information in the object list
  • the static resource contains an interface document configuration template; then, the interface document generation unit is specifically used to render the parameter annotation information obtained by parsing into the interface document configuration template of the static resource to generate an interface document.
  • the parameter annotation information acquisition module 12 is specifically used to: use a code extraction tool to scan the target application code through the interface file path specified in the configuration file to obtain parameter annotation information containing interface information.
  • the code extraction tool is Javadoc in the jdk toolkit.
  • the target application code is annotated in advance using Java annotation specifications.
  • the preset file is a pom file or a gradle file.
  • the interface document generation device 100 disclosed in the present disclosure in the process of generating an interface document, first obtains the target application code in the target project engineering; wherein, this target project engineering is a project engineering to be referenced by a preset file, thereby realizing that the interface document generation device reversely references the engineering to be developed or tested and packages it, rather than the engineering to be developed referencing the component package, and there is no need to modify the target application code except for writing the interface annotation information in accordance with regulations; after packaging the target application code, the target application code is scanned to obtain parameter annotation information containing interface information, and an interface document is generated according to the parameter annotation information.
  • this target project engineering is a project engineering to be referenced by a preset file, thereby realizing that the interface document generation device reversely references the engineering to be developed or tested and packages it, rather than the engineering to be developed referencing the component package, and there is no need to modify the target application code except for writing the interface annotation information in accordance with regulations; after packaging the target application code, the target application code is scanned to obtain
  • FIG. 5 is a block diagram of an interface document generation device 200 provided in an embodiment of the present disclosure, wherein the interface document generation device 200 includes a processor 21, a memory 22, and a memory device 23 stored in the memory device 23.
  • the computer program is a computer program in the processor 22 and can be run on the processor 21.
  • the processor 21 executes the computer program, the steps in the above-mentioned various interface document generation method embodiments are implemented, such as steps S1 to S3.
  • the computer program may be divided into one or more modules/units, which are stored in the memory 22 and executed by the processor 21 to complete the present disclosure.
  • the one or more modules/units may be a series of computer program instruction segments capable of completing specific functions, which are used to describe the execution process of the computer program in the interface document generating device 200.
  • the interface document generating device 200 may include, but is not limited to, a processor 21 and a memory 22. Those skilled in the art may understand that the schematic diagram is merely an example of the interface document generating device 200 and does not constitute a limitation on the interface document generating device 200.
  • the interface document generating device 200 may include more or fewer components than shown in the diagram, or may combine certain components, or different components.
  • the interface document generating device 200 may also include input and output devices, network access devices, buses, etc.
  • the processor 21 may be a central processing unit (CPU), or other general-purpose processors, digital signal processors (DSP), application-specific integrated circuits (ASIC), field-programmable gate arrays (FPGA) or other programmable logic devices, discrete gate or transistor logic devices, discrete hardware components, etc.
  • a general-purpose processor may be a microprocessor or any conventional processor, etc.
  • the processor 21 is the control center of the interface document generation device 200, and uses various interfaces and lines to connect various parts of the entire interface document generation device 200.
  • the memory 22 can be used to store the computer program and/or module.
  • the processor 21 implements various functions of the interface document generating device 200 by running or executing the computer program and/or module stored in the memory 22 and calling the data stored in the memory 22.
  • the memory 22 can mainly include a program storage area and a data storage area, wherein the program storage area can store an operating system, an application required for at least one function (such as a sound playback function, an image playback function, etc.); the data storage area can store an operating system, an application required for at least one function (such as a sound playback function, an image playback function, etc.); The area can store data created according to the use of the mobile phone (such as audio data, phone book, etc.).
  • the memory 22 may include a high-speed random access memory, and may also include a non-volatile memory, such as a hard disk, a memory, a plug-in hard disk, a smart memory card (Smart Media Card, SMC), a secure digital (Secure Digital, SD) card, a flash card (Flash Card), at least one disk storage device, a flash memory device, or other volatile solid-state storage devices.
  • a non-volatile memory such as a hard disk, a memory, a plug-in hard disk, a smart memory card (Smart Media Card, SMC), a secure digital (Secure Digital, SD) card, a flash card (Flash Card), at least one disk storage device, a flash memory device, or other volatile solid-state storage devices.
  • a non-volatile memory such as a hard disk, a memory, a plug-in hard disk, a smart memory card (Smart Media Card, SMC), a secure digital (Secure Digital, SD) card, a flash card
  • the module/unit integrated in the interface document generating device 200 can be stored in a computer-readable storage medium.
  • the present disclosure implements all or part of the processes in the above-mentioned embodiment method, and can also be completed by instructing the relevant hardware through a computer program.
  • the computer program can be stored in a computer-readable storage medium, and when the computer program is executed by the processor 21, the steps of the above-mentioned various method embodiments can be implemented.
  • the computer program includes computer program code, and the computer program code can be in the form of source code, object code, executable file or some intermediate form.
  • the computer-readable medium may include: any entity or device capable of carrying the computer program code, recording medium, U disk, mobile hard disk, magnetic disk, optical disk, computer memory, read-only memory (ROM, Read-Only Memory), random access memory (RAM, Random Access Memory), electric carrier signal, telecommunication signal and software distribution medium, etc.

Landscapes

  • Engineering & Computer Science (AREA)
  • General Engineering & Computer Science (AREA)
  • Theoretical Computer Science (AREA)
  • Software Systems (AREA)
  • Physics & Mathematics (AREA)
  • General Physics & Mathematics (AREA)
  • Computer Security & Cryptography (AREA)
  • Library & Information Science (AREA)
  • Document Processing Apparatus (AREA)
  • Stored Programmes (AREA)

Abstract

本公开公开了一种接口文档生成方法、装置、设备和存储介质，在生成接口文档的过程中，首先获取目标项目工程中的目标应用代码；其中，这一目标项目工程为预设文件待引用的项目工程，由此实现接口文档生成装置反向引用所要开发或测试的工程，对其进行打包，而不是所要开发的工程对组件包进行引用，除按照规定编写接口注释信息外，无需修改目标应用代码；在打包目标应用代码后，对所述目标应用代码进行扫描，得到含有接口信息的参数注释信息，并根据所述参数注释信息生成接口文档。采用本公开实施例，无需使用规范的特殊swagger注解，对程序完全无侵入性，以及无需在项目工程中引入swagger组件，swagger组件不会贯穿软件开发的整个生命周期，提高系统安全性。

Description

接口文档生成方法、装置、设备和存储介质
相关申请的交叉引用
本申请基于申请号为202311633535.8、申请日为2023年11月30日的中国专利申请提出，并要求该中国专利申请的优先权，该中国专利申请的全部内容在此引入本申请作为参考。
技术领域
本公开涉及网络安全领域，尤其涉及一种接口文档生成方法、装置、设备和存储介质。
背景技术
在专网运营平台研发和测试过程中，前端研发或测试人员需要获取在线接口文档并且在在线接口文档上调用相关接口进行调试。现有常用的接口文档生成方式为利用swagger组件生成。swagger组件主要包括程序逻辑、swagger注解标签、swagger前端静态资源。swagger是一款可用于设计、构建、文档化并且执行API的框架。但是，由于swagger组件的使用方法是需要当前工程引入该组件包，即将swagger组件打包至当前工程包，如图1所示，此时的生产环境和测试环境的应用程序包中均含有swagger组件，因此在使用swagger组件生成接口文档时，软件上线后会连带打包的swagger组件上线，由于swagger组件的程序开发者在开发时需要在代码中使用规范的swagger注解，导致其它代码或者设计要做相应的更改以适应新组件，不利于代码的复用，具有一定的侵入性，以及swagger组件会伴随软件开发生命周期从开发、测试到生产一直存在应用程序中，虽然生产环境swagger可对前端页面进行禁用配置，但从历史版本安全漏洞情况看来，已发生过多次安全问题，存在安全漏洞。
发明内容
本公开实施例的目的是提供一种接口文档生成方法、装置、设备和存储介质，无需使用规范的特殊注解，对程序完全无侵入性，无需在项目工程中引入swagger组件，swagger组件不会贯穿软件开发的整个生命周期，提高系统安全性。
为实现上述目的，本公开实施例提供了一种接口文档生成方法，包括：
获取目标项目工程中的目标应用代码；其中，所述目标项目工程为预设文件待引用的项目工程；
对所述目标应用代码进行扫描，得到含有接口信息的参数注释信息；
根据所述参数注释信息生成接口文档。
作为上述方案的改进，所述根据所述参数注释信息生成接口文档，包括：
将所述参数注释信息写入内存的对象列表中；
在所述对象列表中解析出所述参数注释信息，并将解析得到的参数注释信息渲染到静态资源中，生成接口文档。
作为上述方案的改进，所述对所述目标应用代码进行扫描，包括：
利用代码抽取工具通过配置文件中指定的接口文件路径对所述目标应用代码进行扫描。
作为上述方案的改进，所述代码抽取工具包括jdk工具包中的Javadoc。
作为上述方案的改进，所述目标应用代码预先采用Java注释的规范进行注释。
作为上述方案的改进，所述预设文件为pom文件或gradle文件。
作为上述方案的改进，所述静态资源中含有接口文档配置模板；所述将解析得到的参数注释信息渲染到静态资源中，包括：
将解析得到的参数注释信息渲染到所述静态资源的接口文档配置模板中。
为实现上述目的，本公开实施例还提供了一种接口文档生成装置，包括：
目标应用代码打包模块，用于获取目标项目工程中的目标应用代码；其中，所述目标项目工程为预设文件待引用的项目工程；
参数注释信息获取模块，用于对所述目标应用代码进行扫描，得到含有接口信息的参数注释信息；
接口文档生成模块，用于根据所述参数注释信息生成接口文档。
为实现上述目的，本公开实施例还提供了一种接口文档生成设备，包括处理器、存储器以及存储在所述存储器中且被配置为由所述处理器执行的计算机程序，所述处理器执行所述计算机程序时实现如上述任一实施例所述的接口文档生成方法。
为实现上述目的，本公开实施例还提供了一种计算机可读存储介质，所述计算机可读存储介质包括存储的计算机程序，其中，在所述计算机程序运行时控制所述计算机可读存储介质所在设备执行如上述任一实施例所述的接口文档生成方法。
相比于现有技术，本公开公开的接口文档生成方法、装置、设备和存储介质，在生成接口文档的过程中，首先获取目标项目工程中的目标应用代码；其中，这一目标项目工程为预设文件待引用的项目工程，由此实现接口文档生成装置反向引用所要开发或测试的工程，对其进行打包，而不是所要开发的工程对组件包进行引用，除按照规定编写接口注释信息外，无需修改目标应用代码；在打包目标应用代码后，对所述目标应用代码进行扫描，得到含有接口信息的参数注释信息，并根据所述参数注释信息生成接口文档。采用本公开实施例，无需使用规范的特殊swagger注解，对程序完全无侵入性，以及无需在项目工程中引入swagger组件，swagger组件不会贯穿软件开发的整个生命周期，提高系统安全性。
附图说明
图1是现有技术提供的采用swagger组件生成接口文档的示意图；
图2是本公开实施例提供的一种接口文档生成方法的流程图；
图3是本公开实施例提供的一种接口文档生成方法的示意图；
图4是本公开实施例提供的一种接口文档生成装置的结构框图；
图5是本公开实施例提供的一种接口文档生成设备的结构框图。
具体实施方式
下面将结合本公开实施例中的附图，对本公开实施例中的技术方案进行清楚、完整地描述，显然，所描述的实施例仅仅是本公开一部分实施例，而不是全部的实施例。基于本公开中的实施例，本领域普通技术人员在没有作出创造性劳动前提下所获得的所有其他实施例，都属于本公开保护的范围。
参见图2，图2是本公开实施例提供的一种接口文档生成方法的流程图，所述接口文档生成方法应用在测试开发环境中，由文档生成装置执行实现，所述接口文档生成方法包括：
S1、获取目标项目工程中的目标应用代码；其中，所述目标项目工程为预设文件待引用的项目工程；
S2、对所述目标应用代码进行扫描，得到含有接口信息的参数注释信息；
S3、根据所述参数注释信息生成接口文档。
示例性的，生产环境中的应用软件中含有若干个项目工程，所述目标项目工程为需要在测试开发环境中进行测试和调试的项目工程。在生成接口文档的过程中，首先获取目标项目工程中的目标应用代码；其中，这一目标项目工程为测试开发环境中接口文档生成装置中的预设文件需要引用的项目工程，由此实现接口文档生成装置反向引用所要开发或测试的项目工程，对其进行打包，而不是所要开发的项目工程对组件包进行引用，除按照规定编写接口注释信息外，无需修改项目工程的目标应用代码。在打包目标应用代码后，对所述目标应用代码进行扫描，可以得到含有接口信息的参数注释信息，并根据所述参数注释信息生成接口 文档，所述接口文档为在线接口文档，如生成web页面后展示到浏览器页面，以进行在线接口文档的显示及调试，测试人员可进行调试。
示例性的，如图3所示，生产环境中的应用程序包A和应用程序包B为所述目标应用代码，由于无需在项目工程中引入swagger组件，swagger组件不会贯穿软件开发的整个生命周期，生产环境中也不会存在swagger组件或者任意其余能生成接口文档的组件。另外，在测试人员调试测试完成后，软件上线时，在生产环境时仅打包所要上线的业务程序，以pom方式为例，使用mvn package指定打包上线的业务程序，不打包测试开发环境中执行上述步骤S1～S3的文档生成装置，即从根本上规避了测试页面进入生产环境。另外，在测试人员需要对软件进行测试时，只需要暴露所述文档生成装置的ip地址和端口给测试人员，测试人员即可根据ip地址和端口找到文档生成装置，并在开发环境进行相应软件的开发测试。文档生成装置在测试环境中地址和端口可保持不变，即使在容器化环境中，通过反向引用的方式打包后仅需暴露文档生成装置的ip地址和端口即可对接口进行在线模拟调用。
具体地，在步骤S1中，所述目标应用代码预先采用Java注释的规范进行注释。开发人员按照Java注释的规范对软件所要暴露的接口及参数对象字段编写注释comment，而非注解annotation。注释comment与注解annotation是有一定区别的，annotation注解通常需要在目标系统代码侵入式地打上自定义的标签，而comment注释是java文件注释格式，无侵入性，因此在本公开实施例中采用注释comment。
示例性的，用于说明解释程序的文字就是注释。Java中的comment注释类型包括单行注释、多行注释和文档注释(Java特有)，注释是一个程序员必须要具有的良好编程习惯，将自己的思想通过注释先整理出来，再用代码去体现，对于单行和多行注释,被注释的文字,不会被JVM(Java虚拟机)解释执行。注释内容可以被JDK提供的工具Javadoc所解析，生成一套以网页文件形式体现的该程序的说 明文档。
具体地，所述预设文件为pom文件或gradle文件，所述文档生成装置中含有pom文件或gradle文件，通过在pom文件或gradle文件中引用所要开发或测试的项目工程，进而对其进行打包。pom是项目对象模型(Project Object Model)的简称，而pom文件主要描述了项目的maven坐标，该文件用于管理：源代码、配置文件、开发者的信息和角色、问题追踪系统、组织信息、项目授权、项目的url、项目的依赖关系等等，因此，pom文件是项目级别的配置文件。gradle文件是由gradle工具创建的脚本，该脚本是用于帮助团队构建和交付软件的工具，gradle是一个构建工具，它是用来帮助测试人员构建项目的，构建包括编译、打包等过程，测试人员可以为gradle指定构建规则，然后gradle文件就会根据测试人员的“命令”自动构建项目，同理，gradle文件也是项目级别的配置文件。
在本公开实施例中，采用Java注释的规范对软件所要暴露的接口及参数对象字段编写注释，无需使用规范的特殊swagger注解，对程序完全无侵入性。
具体地，在步骤S2中，所述对所述目标应用代码进行扫描，包括：
利用代码抽取工具通过配置文件中指定的接口文件路径对所述目标应用代码进行扫描。
示例性的，测试开发环境需要安装jdk(java开发套件)，所述代码抽取工具为jdk工具包中的Javadoc。通过配置文件中指定的接口文件路径索引到需要扫描的代码，本装置利用配置文件来扫描接口文件范围，例如配置文件中指定的接口文件路径满足：api.scan.location＝com.xxx.controller.*，此时通过jdk工具包中的Javadoc中的$Java_HOME/lib/tools.jar提取到指定范围的含有接口信息的参数注释信息。例如采用Java注释的规范对接口打上如下注释(这一注释即为所述参数注释信息)：
/**
*接口名：求输入两个参数范围以内整数的和
*接口路径：/api/test/add
*接口请求方式：POST
*@param n接收的第一个参数，范围起点
*@param m接收的第二个参数，范围终点
*@return两个参数范围以内整数的和
*/
public int add(int n,int m)。
具体地，所述接口信息包括但不限于接口类型、接口名称、请求参数、返回参数等。如所述接口类型和名称包括：①基于http协议的接口，具体分为get、post、put、delete类型的接口；②基于web service的接口，具体有如下3种：SOAP(simple object access protocol，简单对象访问协议)类型、RMI(Remote Method Invocation,远程方法调用)类型和RPC(Remote Procedure Calls，远程过程调用)类型；如所述请求参数http请求，则返回参数为与所述http请求对应的参数。
具体地，在步骤S3中，所述根据所述参数注释信息生成接口文档，包括：
S21、将所述参数注释信息写入内存的对象列表中；
S22、在所述对象列表中解析出所述参数注释信息，并将解析得到的参数注释信息渲染到静态资源中，生成接口文档。
示例性的，Java是一门面向对象编程语言，在Java当中，对象是一个类的实体，对象实现了一些相关的数据和算法的封装。接口文档生成装置将所述参数注释信息写入到Java内存中的对象列表中，以封装所述参数注释信息，可以理解的，所述对象列表中含有若干个对象，一个对象可对应封装一个参数注释信息(即对应一个接口的接口信息)，然后接口文档生成装置再从Java对象列表中解析出所述参数注释信息，并将解析得到的参数注释信息渲染到静态资源中，将数据渲染入静态资源后才能产生web浏览器可识别的html等资源，由此生成对 外接口信息及在线接口调用界面的接口文档，测试人员可在此在线接口文档上进行接口调试。
具体地，在步骤S22中，所述静态资源中含有接口文档配置模板；则，所述将解析得到的参数注释信息渲染到静态资源中，包括：
将解析得到的参数注释信息渲染到所述静态资源的接口文档配置模板中。
示例性的，所述接口文档配置模板中至少包括接口名称、接口调用路径、接口入参信息、接口出参信息、接口请求方式这些信息。
相比于现有技术，本公开公开的接口文档生成方法，在生成接口文档的过程中，首先获取目标项目工程中的目标应用代码；其中，这一目标项目工程为预设文件待引用的项目工程，由此实现接口文档生成装置反向引用所要开发或测试的工程，对其进行打包，而不是所要开发的工程对组件包进行引用，除按照规定编写接口注释信息外，无需修改目标应用代码；在打包目标应用代码后，对所述目标应用代码进行扫描，得到含有接口信息的参数注释信息，并根据所述参数注释信息生成接口文档。采用本公开实施例，无需使用规范的特殊swagger注解，对程序完全无侵入性，以及无需在项目工程中引入swagger组件，swagger组件不会贯穿软件开发的整个生命周期，提高系统安全性。
参见图4，图4是本公开实施例提供的一种接口文档生成装置100的结构框图，所述接口文档生成装置100包括：
目标应用代码打包模块11，用于获取目标项目工程中的目标应用代码；其中，所述目标项目工程为预设文件待引用的项目工程；
参数注释信息获取模块12，用于对所述目标应用代码进行扫描，得到含有接口信息的参数注释信息；
接口文档生成模块13，用于根据所述参数注释信息生成接口文档。
具体地，所述接口文档生成模块13包括：
对象写入单元，用于将所述参数注释信息写入内存的对象列表中；
解析单元，用于在所述对象列表中解析出所述参数注释信息；
接口文档生成单元，用于将解析得到的参数注释信息渲染到静态资源中，生成接口文档。
具体地，所述静态资源中含有接口文档配置模板；则，所述接口文档生成单元具体用于：将解析得到的参数注释信息渲染到所述静态资源的接口文档配置模板中，生成接口文档。
具体地，所述参数注释信息获取模块12具体用于：利用代码抽取工具通过配置文件中指定的接口文件路径对所述目标应用代码进行扫描，得到含有接口信息的参数注释信息。
具体地，所述代码抽取工具为jdk工具包中的Javadoc。
具体地，所述目标应用代码预先采用Java注释的规范进行注释。
具体地，所述预设文件为pom文件或gradle文件。
相比于现有技术，本公开公开的接口文档生成装置100，在生成接口文档的过程中，首先获取目标项目工程中的目标应用代码；其中，这一目标项目工程为预设文件待引用的项目工程，由此实现接口文档生成装置反向引用所要开发或测试的工程，对其进行打包，而不是所要开发的工程对组件包进行引用，除按照规定编写接口注释信息外，无需修改目标应用代码；在打包目标应用代码后，对所述目标应用代码进行扫描，得到含有接口信息的参数注释信息，并根据所述参数注释信息生成接口文档。采用本公开实施例，无需使用规范的特殊swagger注解，对程序完全无侵入性，以及无需在项目工程中引入swagger组件，swagger组件不会贯穿软件开发的整个生命周期，提高系统安全性。
参见图5，图5是本公开实施例提供的一种接口文档生成设备200的结构框图，所述接口文档生成设备200包括处理器21、存储器22以及存储在所述存储 器22中并可在所述处理器21上运行的计算机程序。所述处理器21执行所述计算机程序时实现上述各个接口文档生成方法实施例中的步骤，比如步骤S1～S3。
示例性的，所述计算机程序可以被分割成一个或多个模块/单元，所述一个或者多个模块/单元被存储在所述存储器22中，并由所述处理器21执行，以完成本公开。所述一个或多个模块/单元可以是能够完成特定功能的一系列计算机程序指令段，该指令段用于描述所述计算机程序在所述接口文档生成设备200中的执行过程。
所述接口文档生成设备200可包括，但不仅限于，处理器21、存储器22。本领域技术人员可以理解，所述示意图仅仅是接口文档生成设备200的示例，并不构成对接口文档生成设备200的限定，可以包括比图示更多或更少的部件，或者组合某些部件，或者不同的部件，例如所述接口文档生成设备200还可以包括输入输出设备、网络接入设备、总线等。
所述处理器21可以是中央处理单元(Central Processing Unit，CPU)，还可以是其他通用处理器、数字信号处理器(Digital Signal Processor，DSP)、专用集成电路(Application Specific Integrated Circuit，ASIC)、现成可编程门阵列(Field-Programmable Gate Array，FPGA)或者其他可编程逻辑器件、分立门或者晶体管逻辑器件、分立硬件组件等。通用处理器可以是微处理器或者该处理器也可以是任何常规的处理器等，所述处理器21是所述接口文档生成设备200的控制中心，利用各种接口和线路连接整个接口文档生成设备200的各个部分。
所述存储器22可用于存储所述计算机程序和/或模块，所述处理器21通过运行或执行存储在所述存储器22内的计算机程序和/或模块，以及调用存储在存储器22内的数据，实现所述接口文档生成设备200的各种功能。所述存储器22可主要包括存储程序区和存储数据区，其中，存储程序区可存储操作系统、至少一个功能所需的应用程序(比如声音播放功能、图像播放功能等)等；存储数据 区可存储根据手机的使用所创建的数据(比如音频数据、电话本等)等。此外，存储器22可以包括高速随机存取存储器，还可以包括非易失性存储器，例如硬盘、内存、插接式硬盘，智能存储卡(Smart Media Card,SMC)，安全数字(Secure Digital,SD)卡，闪存卡(Flash Card)、至少一个磁盘存储器件、闪存器件、或其他易失性固态存储器件。
其中，所述接口文档生成设备200集成的模块/单元如果以软件功能单元的形式实现并作为独立的产品销售或使用时，可以存储在一个计算机可读取存储介质中。基于这样的理解，本公开实现上述实施例方法中的全部或部分流程，也可以通过计算机程序来指令相关的硬件来完成，所述的计算机程序可存储于一计算机可读存储介质中，该计算机程序在被处理器21执行时，可实现上述各个方法实施例的步骤。其中，所述计算机程序包括计算机程序代码，所述计算机程序代码可以为源代码形式、对象代码形式、可执行文件或某些中间形式等。所述计算机可读介质可以包括：能够携带所述计算机程序代码的任何实体或装置、记录介质、U盘、移动硬盘、磁碟、光盘、计算机存储器、只读存储器(ROM，Read-Only Memory)、随机存取存储器(RAM，Random Access Memory)、电载波信号、电信信号以及软件分发介质等。
以上所述是本公开的优选实施方式，应当指出，对于本技术领域的普通技术人员来说，在不脱离本公开原理的前提下，还可以做出若干改进和润饰，这些改进和润饰也视为本公开的保护范围。

Claims (18)

  1. 一种接口文档生成方法，其特征在于，包括：
    获取目标项目工程中的目标应用代码；其中，所述目标项目工程为预设文件待引用的项目工程；
    对所述目标应用代码进行扫描，得到含有接口信息的参数注释信息；
    根据所述参数注释信息生成接口文档。
  2. 如权利要求1所述的接口文档生成方法，其特征在于，所述根据所述参数注释信息生成接口文档，包括：
    将所述参数注释信息写入内存的对象列表中；
    在所述对象列表中解析出所述参数注释信息，并将解析得到的参数注释信息渲染到静态资源中，生成所述接口文档。
  3. 如权利要求1或2所述的接口文档生成方法，其特征在于，所述对所述目标应用代码进行扫描，包括：
    利用代码抽取工具通过配置文件中指定的接口文件路径对所述目标应用代码进行扫描。
  4. 如权利要求3所述的接口文档生成方法，其特征在于，所述代码抽取工具包括jdk工具包中的Javadoc。
  5. 如权利要求1-4任一项所述的接口文档生成方法，其特征在于，所述目标应用代码预先采用Java注释的规范进行注释。
  6. 如权利要求1-5任一项所述的接口文档生成方法，其特征在于，所述预设文件为pom文件或gradle文件。
  7. 如权利要求2所述的接口文档生成方法，其特征在于，所述静态资源中含有接口文档配置模板；所述将解析得到的参数注释信息渲染到静态资源中，包括：
    将解析得到的参数注释信息渲染到所述静态资源的接口文档配置模板中。
  8. 一种接口文档生成装置，其特征在于，包括：
    目标应用代码打包模块，用于获取目标项目工程中的目标应用代码；其中，所述目标项目工程为预设文件待引用的项目工程；
    参数注释信息获取模块，用于对所述目标应用代码进行扫描，得到含有接口信息的参数注释信息；
    接口文档生成模块，用于根据所述参数注释信息生成接口文档。
  9. 如权利要求8所述的接口文档生成装置，其特征在于，所述接口文档生成模块包括：
    对象写入单元，用于将所述参数注释信息写入内存的对象列表中；
    解析单元，用于在所述对象列表中解析出所述参数注释信息；
    接口文档生成单元，用于将解析得到的参数注释信息渲染到静态资源中，生成所述接口文档。
  10. 如权利要求8或9所述的接口文档生成装置，其特征在于，所述参数注释信息获取模块用于：
    利用代码抽取工具通过配置文件中指定的接口文件路径对所述目标应用代码进行扫描。
  11. 如权利要求10所述的接口文档生成装置，其特征在于，所述代码抽取工具包括jdk工具包中的Javadoc。
  12. 如权利要求8-11任一项所述的接口文档生成装置，其特征在于，所述目标应用代码预先采用Java注释的规范进行注释。
  13. 如权利要求8-12任一项所述的接口文档生成装置，其特征在于，所述预设文件为pom文件或gradle文件。
  14. 如权利要求9所述的接口文档生成装置，其特征在于，所述静态资源中含有接口文档配置模板；所述接口文档生成单元具体用于：
    将解析得到的参数注释信息渲染到所述静态资源的接口文档配置模板中。
  15. 一种接口文档生成设备，其特征在于，包括处理器、存储器以及存储在所述存储器中且被配置为由所述处理器执行的计算机程序，所述处理器执行所述计算机程序时实现如权利要求1至7中任意一项所述的接口文档生成方法。
  16. 一种计算机可读存储介质，其特征在于，所述计算机可读存储介质包括存储的计算机程序，其中，在所述计算机程序运行时控制所述计算机可读存储介质所在设备执行如权利要求1至7中任意一项所述的接口文档生成方法。
  17. 一种计算机程序产品，其特征在于，当所述计算机程序中的指令由电子设备执行时实现如权利要求1-7任意一项所述的基于交通资源的行程规划方法。
  18. 一种计算机程序，其特征在于，所述计算机程序被电子设备执行时实现如权利要求1-7任意一项所述的基于交通资源的行程规划方法。
PCT/CN2024/113797 2023-11-30 2024-08-21 接口文档生成方法、装置、设备和存储介质 Pending WO2025112699A1 (zh)

Applications Claiming Priority (2)

Application Number Priority Date Filing Date Title
CN202311633535.8 2023-11-30
CN202311633535.8A CN118819625A (zh) 2023-11-30 2023-11-30 接口文档生成方法、装置、设备和存储介质

Publications (1)

Publication Number Publication Date
WO2025112699A1 true WO2025112699A1 (zh) 2025-06-05

Family

ID=93084469

Family Applications (1)

Application Number Title Priority Date Filing Date
PCT/CN2024/113797 Pending WO2025112699A1 (zh) 2023-11-30 2024-08-21 接口文档生成方法、装置、设备和存储介质

Country Status (2)

Country Link
CN (1) CN118819625A (zh)
WO (1) WO2025112699A1 (zh)

Citations (5)

* Cited by examiner, † Cited by third party
Publication number Priority date Publication date Assignee Title
CN112416430A (zh) * 2020-11-27 2021-02-26 亿企赢网络科技有限公司 一种接口文档生成方法、装置、设备及存储介质
CN112540862A (zh) * 2020-12-23 2021-03-23 东莞市盟大塑化科技有限公司 一种接口文档数据生成方法、装置、设备及存储介质
US20210224062A1 (en) * 2020-01-17 2021-07-22 Accenture Global Solutions Limited Systems and Methods for Software Documentation and Code Generation Management
CN113961239A (zh) * 2021-11-12 2022-01-21 中国工商银行股份有限公司 接口文档显示方法、装置、存储介质及电子设备
CN114443129A (zh) * 2021-12-30 2022-05-06 广东南方新媒体科技有限公司 一种项目文档自动化生成方法、设备及存储介质

Patent Citations (5)

* Cited by examiner, † Cited by third party
Publication number Priority date Publication date Assignee Title
US20210224062A1 (en) * 2020-01-17 2021-07-22 Accenture Global Solutions Limited Systems and Methods for Software Documentation and Code Generation Management
CN112416430A (zh) * 2020-11-27 2021-02-26 亿企赢网络科技有限公司 一种接口文档生成方法、装置、设备及存储介质
CN112540862A (zh) * 2020-12-23 2021-03-23 东莞市盟大塑化科技有限公司 一种接口文档数据生成方法、装置、设备及存储介质
CN113961239A (zh) * 2021-11-12 2022-01-21 中国工商银行股份有限公司 接口文档显示方法、装置、存储介质及电子设备
CN114443129A (zh) * 2021-12-30 2022-05-06 广东南方新媒体科技有限公司 一种项目文档自动化生成方法、设备及存储介质

Also Published As

Publication number Publication date
CN118819625A (zh) 2024-10-22

Similar Documents

Publication Publication Date Title
CN103294598B (zh) 一种源代码检查方法及装置
CN111124906A (zh) 基于动态埋点的跟踪方法、编译方法、装置和电子设备
CN112114890A (zh) 小程序的处理方法、装置、设备及存储介质
CN103176892B (zh) 一种页面监控方法及系统
CN113778405A (zh) 一种跨平台app构建方法、装置、系统及介质
CN111913741A (zh) 对象拦截方法、装置、介质及电子设备
CN112395098A (zh) 应用程序接口调用方法、装置、存储介质和电子设备
CN111858376A (zh) 请求报文生成方法和接口测试方法
CN110134380B (zh) 一种基于模板引擎的代码生成方法、装置及电子设备
WO2016095570A1 (zh) 一种嵌入式系统的调试方法及装置、存储介质
CN114428613A (zh) 一种流程编排方法、系统、介质及计算机程序产品
JP2010140408A (ja) ソースコード変換装置
CN112433929B (zh) 网页调试方法、装置、计算机设备和存储介质
CN114721713A (zh) 基于注解的数据处理方法、计算机设备以及可读存储介质
CN112631590A (zh) 组件库生成方法、装置、电子设备和计算机可读介质
CN106610845B (zh) 信息管理方法、装置、服务器及系统
JP2010140407A (ja) ソースコード検査装置
CN112052051B (zh) 插件处理方法、装置、设备及存储介质
WO2020073200A1 (zh) 调试程序的方法和系统
WO2025112699A1 (zh) 接口文档生成方法、装置、设备和存储介质
CN114721929A (zh) 测试方法、装置、存储介质及设备
CN113467815A (zh) 热更新的应用修复方法、装置、终端设备及存储介质
US20110321009A1 (en) Implementing encryption via aspect oriented programming
CN113641594B (zh) 跨端自动化测试方法以及相关装置
CN115268985B (zh) 一种用于RPC服务的Mock方法、装置及计算机可读存储介质

Legal Events

Date Code Title Description
121 Ep: the epo has been informed by wipo that ep was designated in this application

Ref document number: 24895800

Country of ref document: EP

Kind code of ref document: A1