Interface document generation method, apparatus and device, and storage medium

Abstract

Disclosed in the present disclosure are an interface document generation method, apparatus and device, and a storage medium. The method comprises: in the process of generating an interface document, first acquiring a target application code in target project engineering in the process of generating an interface document, wherein the target project engineering is project engineering to be referenced by a preset file, thereby enabling an interface document generation apparatus to reversely reference a project to be developed or tested and to package said project, rather than the project to be developed referencing a component package, and except for writing interface annotation information according to regulations, the target application code does not need to be modified; and after the target application code is packaged, scanning the target application code, so as to obtain parameter annotation information containing interface information, and generating an interface document on the basis of the parameter annotation information. By means of using the embodiments of the present disclosure, there is no need to use standard special swagger annotations, which is completely non-invasive to a program, and there is no need to introduce swagger components into project engineering, and the swagger components do not persist throughout the entire life cycle of software development, thereby improving the system security.

Description

Interface document generation method, device, equipment and storage medium

[0001] CROSS-REFERENCE TO RELATED APPLICATIONS

[0002] This application is based on the Chinese patent application with application number 202311633535.8 and application date of November 30, 2023, and claims the priority of the Chinese patent application. The entire content of the Chinese patent application is hereby introduced into this application as a reference. Technical Field

[0003] The present disclosure relates to the field of network security, and in particular to a method, apparatus, device, and storage medium for generating an interface document. Background Art

[0004] During the development and testing of private network operation platforms, front-end developers or testers need to access online interface documentation and call relevant interfaces within it for debugging. A common method for generating interface documentation is using the Swagger component. The Swagger component primarily includes program logic, Swagger annotation tags, and Swagger front-end static resources. Swagger is a framework for designing, building, documenting, and executing APIs. However, since 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. Therefore, when using the swagger component to generate interface documents, 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 certain invasiveness. The swagger component will exist in the application from development and testing to production throughout the software development life cycle. Although the production environment swagger can disable the front-end page configuration, judging from the security vulnerabilities of historical versions, many security issues have occurred and security vulnerabilities exist.

[0005] Summary of the Invention

[0006] 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.

[0007] To achieve the above objectives, the present disclosure provides a method for generating an interface document, comprising:

[0008] Obtaining a target application code in a target project; wherein the target project is a project to be referenced by a preset file;

[0009] Scan the target application code to obtain parameter annotation information containing interface information;

[0010] Generate an interface document based on the parameter annotation information.

[0011] As an improvement to the above solution, generating an interface document according to the parameter annotation information includes:

[0012] Writing the parameter annotation information into the object list in the memory;

[0013] 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.

[0014] As an improvement to the above solution, scanning the target application code includes:

[0015] The target application code is scanned using a code extraction tool through the interface file path specified in the configuration file.

[0016] As an improvement of the above solution, the code extraction tool includes Javadoc in the JDK toolkit.

[0017] As an improvement to the above solution, the target application code is annotated in advance using Java annotation standards.

[0018] As an improvement to the above solution, the preset file is a pom file or a gradle file.

[0019] As an improvement to the above solution, the static resource contains an interface document configuration template; rendering the parsed parameter annotation information into the static resource includes:

[0020] The parameter annotation information obtained by parsing is rendered into the interface document configuration template of the static resource.

[0021] To achieve the above-mentioned purpose, the present disclosure also provides an interface document generation device, comprising:

[0022] A target application code packaging module is used to obtain the target application code in the target project; wherein the target project is a project to be referenced by the preset file;

[0023] A parameter annotation information acquisition module is used to scan the target application code to obtain parameter annotation information containing interface information;

[0024] The interface document generation module is used to generate an interface document according to the parameter annotation information.

[0025] To achieve the above-mentioned purpose, an embodiment of the present disclosure also provides an interface document generation device, comprising a processor, a memory, and a computer program stored in the memory and configured to be executed by the processor, wherein when the processor executes the computer program, the interface document generation method as described in any of the above-mentioned embodiments is implemented.

[0026] To achieve the above-mentioned purpose, an embodiment of the present disclosure also provides a computer-readable storage medium, which 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.

[0027] Compared with the prior art, the interface document generation method, device, equipment and storage medium disclosed in the present invention, 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 the project engineering to be referenced by the preset file, thereby realizing that the interface document generation device reversely references the project to be developed or tested and packages it, rather than the project 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 the interface information, and an interface document is generated based on the parameter annotation information. By adopting the embodiment of the present disclosure, there is no need to use the standardized special swagger annotation, which is completely non-invasive to the program, and 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 software development, thereby improving system security. BRIEF DESCRIPTION OF THE DRAWINGS

[0028] FIG1 is a schematic diagram of generating an interface document using a swagger component provided by the prior art;

[0029] FIG2 is a flow chart of a method for generating an interface document provided by an embodiment of the present disclosure;

[0030] FIG3 is a schematic diagram of a method for generating an interface document provided by an embodiment of the present disclosure;

[0031] FIG4 is a structural block diagram of an interface document generating device provided by an embodiment of the present disclosure;

[0032] FIG5 is a structural block diagram of an interface document generating device provided by an embodiment of the present disclosure. DETAILED DESCRIPTION

[0033] The following will clearly and completely describe the technical solutions in the embodiments of the present disclosure in conjunction with the accompanying drawings. Obviously, the described embodiments are only part of the embodiments of the present disclosure, not all of the embodiments. All other embodiments obtained by ordinary technicians in this field based on the embodiments of the present disclosure without making any creative efforts shall fall within the scope of protection of the present disclosure.

[0034] Referring to FIG. 2 , 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:

[0035] S1. Obtain target application code in a target project; wherein the target project is a project to be referenced by a preset file;

[0036] S2. Scan the target application code to obtain parameter annotation information containing interface information;

[0037] S3. Generate an interface document according to the parameter annotation information.

[0038] Exemplarily, 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. In the process of generating the interface document, the target application code in the target project project is first obtained; wherein, this target project project is the project project that needs to be referenced by the preset file in the interface document generation device in the test development environment, thereby realizing that the interface document generation device reversely references the project project to be developed or tested and packages it, instead of the project project to be developed referencing the component package. Except for writing the interface annotation information in accordance with the regulations, there is no need to modify the target application code of the project project. 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 based on the parameter annotation information. The interface document is an online interface document, such as displaying it on a browser page after generating a web page, so as to display and debug the online interface document, and the tester can perform debugging.

[0039] For example, as shown in Figure 3, application packages A and B in the production environment represent the target application code. Since the Swagger component is not required in the project, it will not be present throughout the entire software development lifecycle. Neither the Swagger component nor any other components capable of generating interface documentation will be present in the production environment. Furthermore, after the tester completes debugging and testing, when the software is released, only the business applications to be released are packaged in the production environment. For example, using the pom package method, the business applications to be released are packaged using mvn package. The document generation device that performs steps S1-S3 in the test development environment is not packaged, thus fundamentally preventing the test page from entering the production environment. Furthermore, when the tester needs to test the software, they only need to expose the IP address and port number of the document generation device. The tester can then locate the document generation device based on the IP address and port number and conduct development testing of the corresponding software in the development environment. The document generation device's address and port number remain unchanged in the test environment. Even in a containerized environment, after packaging, by back-reference, only the IP address and port number of the document generation device need to be exposed to simulate online calls to the interface.

[0040] Specifically, in step S1, the target application code is pre-annotated using Java annotation specifications. Developers write comments, rather than annotations, for the interfaces and parameter object fields to be exposed by the software according to Java annotation specifications. Comments are different from annotations. Annotations typically require intrusive application of custom tags to the target system code, while comments are in the Java file comment format and are non-intrusive. Therefore, comments are used in the disclosed embodiments.

[0041] For example, comments are text used to explain and interpret a program. Java comment types include single-line comments, multi-line comments, and documentation comments (specific to Java). Commenting is a good programming habit that programmers must develop. Comments are used to organize ideas and then reflect them in code. Single-line and multi-line comments are not interpreted by the JVM (Java Virtual Machine). Comments can be parsed by the Javadoc tool provided by the JDK to generate a set of program documentation in the form of a web page.

[0042] Specifically, the preset file is a pom file or a gradle file, and the document generation device contains a pom file or a gradle file, which is used to reference the project to be developed or tested in the pom file or the gradle file and then package it. pom is the abbreviation of Project Object Model, and 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 for helping 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". Similarly, the gradle file is also a project-level configuration file.

[0043] In the disclosed embodiment, the Java annotation specification is used to write annotations for the interfaces and parameter object fields to be exposed by the software, without the need to use the standard special swagger annotations, and it is completely non-invasive to the program.

[0044] Specifically, in step S2, scanning the target application code includes:

[0045] The target application code is scanned using a code extraction tool through the interface file path specified in the configuration file.

[0046] For example, the test development environment requires the installation of 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. For example, the interface file path specified in the configuration file satisfies: api.scan.location = com.xxx.controller.*. At this time, the parameter annotation information containing the interface information in the specified range is extracted through $Java_HOME / lib / tools.jar in the Javadoc in the jdk toolkit. For example, the interface is annotated as follows using the Java annotation specification (this annotation is the parameter annotation information):

[0047] / **

[0048] *Interface name: Find the sum of two integers within the input parameter range

[0049] *Interface path: / api / test / add

[0050] *Interface request method: POST

[0051] *@param n receives the first parameter, the starting point of the range

[0052] *@param m receives the second parameter, the end point of the range

[0053] *@return the sum of integers within the range of two parameters

[0054] * /

[0055] public int add(int n, int m).

[0056] Specifically, the interface information includes, but is not limited to, the interface type, interface name, request parameters, and return parameters. For example, the interface type and name include: ① HTTP-based interfaces, specifically categorized as get, post, put, and delete interfaces; ② Web service-based interfaces, specifically categorized as the following three types: SOAP (simple object access protocol), RMI (Remote Method Invocation), and RPC (Remote Procedure Calls); if the request parameters are HTTP requests, the return parameters are the parameters corresponding to the HTTP request.

[0057] Specifically, in step S3, generating an interface document according to the parameter annotation information includes:

[0058] S21, writing the parameter annotation information into an object list in a memory;

[0059] S22: parse the parameter annotation information in the object list, and render the parsed parameter annotation information into static resources to generate an interface document.

[0060] For example, Java is an object-oriented programming language. In Java, 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. It can be understood that the object list contains several objects, and one object can encapsulate a parameter annotation information (i.e., the interface information corresponding to an interface). Then 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 the interface document of the external interface information and the online interface call interface. The tester can perform interface debugging on this online interface document.

[0061] Specifically, in step S22, the static resource contains an interface document configuration template; then, rendering the parsed parameter annotation information into the static resource includes:

[0062] The parameter annotation information obtained by parsing is rendered into the interface document configuration template of the static resource.

[0063] Exemplarily, 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.

[0064] Compared with the prior art, the interface document generation method disclosed in the present invention, 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 the project engineering to be referenced by the preset file, thereby realizing that the interface document generation device reversely references the project to be developed or tested and packages it, rather than the project 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 based on the parameter annotation information. By adopting the embodiment of the present disclosure, there is no need to use the standardized special swagger annotation, which is completely non-invasive to the program, and 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 software development, thereby improving system security.

[0065] 4 , which is a structural block diagram of an interface document generation device 100 provided in an embodiment of the present disclosure, the interface document generation device 100 includes:

[0066] The target application code packaging module 11 is used to obtain the target application code in the target project; wherein the target project is a project to be referenced by the preset file;

[0067] A parameter annotation information acquisition module 12 is used to scan the target application code to obtain parameter annotation information containing interface information;

[0068] The interface document generating module 13 is used to generate an interface document according to the parameter annotation information.

[0069] Specifically, the interface document generation module 13 includes:

[0070] An object writing unit, configured to write the parameter annotation information into an object list in a memory;

[0071] A parsing unit, configured to parse the object list to obtain the parameter annotation information;

[0072] The interface document generation unit is used to render the parsed parameter annotation information into static resources to generate the interface document.

[0073] Specifically, 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.

[0074] Specifically, 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.

[0075] Specifically, the code extraction tool is Javadoc in the JDK toolkit.

[0076] Specifically, the target application code is annotated in advance using Java annotation specifications.

[0077] Specifically, the preset file is a pom file or a gradle file.

[0078] Compared with the prior art, the interface document generation device 100 disclosed in the present invention, 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 project to be developed or tested and packages it, rather than the project 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 based on the parameter annotation information. By adopting the embodiment of the present disclosure, there is no need to use standardized special swagger annotations, which is completely non-invasive to the program, and there is no need to introduce swagger components in the project engineering. The swagger components will not run through the entire life cycle of software development, thereby improving system security.

[0079] Referring to FIG5 , FIG5 is a structural block diagram of an interface document generation device 200 provided in an embodiment of the present disclosure. The interface document generation device 200 includes a processor 21, a memory 22, and a computer program stored in the memory 22 and executable on the processor 21. When the processor 21 executes the computer program, the steps in the above-mentioned various embodiments of the interface document generation method are implemented, such as steps S1 to S3.

[0080] Exemplarily, 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 implement the present disclosure. The one or more modules / units may be a series of computer program instruction segments capable of implementing specific functions, and the instruction segments are used to describe the execution process of the computer program in the interface document generating device 200.

[0081] 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 will appreciate that the schematic diagram is merely an example of the interface document generating device 200 and does not limit 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. For example, the interface document generating device 200 may also include input and output devices, network access devices, buses, and the like.

[0082] 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. The processor 21 is the control center of the interface document generation device 200, and utilizes various interfaces and lines to connect various parts of the entire interface document generation device 200.

[0083] The memory 22 can be used to store the computer programs and / or modules. The processor 21 implements the various functions of the interface document generation device 200 by running or executing the computer programs and / or modules 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. The program storage area can store an operating system and at least one application required for a function (such as a sound playback function, an image playback function, etc.); the data storage area can store data created based on the use of the mobile phone (such as audio data, a phone book, etc.). In addition, the memory 22 can include a high-speed random access memory and a non-volatile memory, such as a hard disk, a memory, a plug-in hard disk, a smart media card (SMC), a secure digital (SD) card, a flash card, at least one disk storage device, a flash memory device, or other volatile solid-state storage device.

[0084] Wherein, if the module / unit integrated in the interface document generating device 200 is implemented in the form of a software functional unit and sold or used as an independent product, it can be stored in a computer-readable storage medium. Based on this understanding, 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, it can implement the steps of the above-mentioned various method embodiments. Wherein, the computer program includes computer program code, and the computer program code can be in source code form, object code form, executable file or some intermediate form, etc. The computer-readable medium may include: any entity or device that can carry 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), electrical carrier signal, telecommunication signal and software distribution medium, etc.

[0085] The above is a preferred embodiment of the present disclosure. It should be pointed out that for ordinary technicians in this technical field, several improvements and modifications can be made without departing from the principles of the present disclosure. These improvements and modifications are also considered to be within the scope of protection of the present disclosure.

Claims

1. A method for generating an interface document, characterized in that: include: Obtaining a target application code in a target project; wherein the target project is a project to be referenced by a preset file; Scanning the target application code to obtain parameter annotation information containing interface information; Generate an interface document according to the parameter annotation information.

2. The interface document generation method according to claim 1, characterized in that: The generating an interface document according to the parameter annotation information includes: Writing the parameter annotation information into the object list in the memory; 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 the interface document.

3. The interface document generation method according to claim 1 or 2, characterized in that: The scanning of 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.

4. The interface document generation method according to claim 3, characterized in that: The code extraction tool includes Javadoc in the jdk toolkit.

5. The interface document generation method according to any one of claims 1 to 4, characterized in that: The target application code is annotated in advance using Java annotation specifications.

6. The interface document generation method according to any one of claims 1 to 5, characterized in that: The preset file is a pom file or a gradle file.

7. The interface document generation method according to claim 2, characterized in that: 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.

8. An interface document generating device, characterized in that: include: 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.

9. The interface document generating device according to claim 8, characterized in that: The interface document generation module 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 interface document generation unit is used to render the parameter annotation information obtained by parsing into static resources to generate the interface document.

10. The interface document generating device according to claim 8 or 9, characterized in that: The parameter annotation information acquisition module is used for: The target application code is scanned using a code extraction tool through the interface file path specified in the configuration file.

11. The interface document generating device according to claim 10, characterized in that: The code extraction tool includes Javadoc in the jdk toolkit.

12. The interface document generating device according to any one of claims 8 to 11, characterized in that: The target application code is annotated in advance using Java annotation specifications.

13. The interface document generating device according to any one of claims 8 to 12, characterized in that: The preset file is a pom file or a gradle file.

14. The interface document generating device according to claim 9, characterized in that: The static resource contains an interface document configuration template; the interface document generation unit is specifically used to: The parameter annotation information obtained by parsing is rendered into the interface document configuration template of the static resource.

15. An interface document generating device, characterized in that: The method comprises a processor, a memory, and a computer program stored in the memory and configured to be executed by the processor, wherein the processor implements the interface document generation method as described in any one of claims 1 to 7 when executing the computer program.

16. A computer-readable storage medium, characterized in that: The computer-readable storage medium includes a stored computer program, wherein when the computer program is executed, the device where the computer-readable storage medium is located is controlled to execute the interface document generation method according to any one of claims 1 to 7.

17. A computer program product, characterized in that When the instructions in the computer program are executed by an electronic device, the method for itinerary planning based on traffic resources as described in any one of claims 1 to 7 is implemented.

18. A computer program, characterized in that When the computer program is executed by an electronic device, the method for itinerary planning based on traffic resources as described in any one of claims 1 to 7 is implemented.

Images