Method, system and storage medium for generating custom API documents based on Swagger and Word

Abstract

This invention discloses a method for generating a custom API document based on Swagger and Word, comprising the following sequential steps: S1: defining a Word interface document, replacing dynamic interface data with placeholders and transferring it to Minio; S2: introducing Swagger-related dependency packages into a system project and configuring the project paths that Swagger needs to scan; S3: filling in the API interface data defined by the Swagger framework when developing the system project interface; and steps S4-S11. This invention uses an automated process to automatically extract all API interface data specified in the OpenAPI specification from the API interface provided by Swagger, and then automatically fills the obtained API interface data into the custom Word interface document, eliminating the tediousness of traditional manual document filling while also improving the efficiency and accuracy of document generation.

Description

Technical Field

[0001] The present invention relates to the field of API documents, and in particular to a method, system and storage medium for generating custom API documents based on Swagger and Word. Background Art

[0002] In today's technological landscape, integration and interoperability between disparate systems are becoming increasingly common. This inter-system communication occurs through application programming interfaces (APIs), which bridge data and functionality between software systems. With the emergence of diverse applications and services, and the need for collaboration between diverse organizations, API documentation has become a critical component for ensuring effective communication and collaboration.

[0003] Traditionally, API documentation is usually a manual and tedious process. Developers must manually enter API endpoints, parameters, responses and other information one by one, and constantly track changes to maintain the accuracy of the documentation. This approach easily leads to poor documentation accuracy.

[0004] In view of this, the inventors of this case conducted in-depth research on the above-mentioned issues, which led to the creation of this case. Summary of the Invention

[0005] The object of the present invention is to provide a method, system and storage medium for generating custom API documents based on Swagger and Word, which can improve the accuracy of API documents.

[0006] In order to achieve the above object, the present invention adopts such technical solution:

[0007] The method for generating custom API documentation based on Swagger and Word includes the following steps:

[0008] S1: Define a Word interface document, in which the interface dynamic data is replaced with placeholders and transmitted to minio;

[0009] S2: Introduce swagger-related dependency packages into the system engineering and configure the project path that swagger needs to scan;

[0010] S3: When developing the interface of the system engineering, fill in the API interface data defined by the swagger framework;

[0011] S4: When the system project is started, Swagger automatically scans all the API interface data on the system project, and respectively encapsulates the API interface data into data in the apenapi standard format and provides the corresponding API interface to the outside world;

[0012] S5: Call the API interface provided by Swagger and obtain all the API interface data specified in the OpenAPI specification through an HTTP request;

[0013] S6: extracting required API interface data from all the API interface data generated in S5, filtering out unnecessary API interface data, and storing the extracted API interface data in the system engineering for subsequent processing;

[0014] S7: Download the Word interface document defined in S1 through minio;

[0015] S8: Use the open source Apache POI library to operate the Word interface document downloaded in S7, and fill the API interface data extracted in S6 into the corresponding position in the Word interface document;

[0016] S9: Name the Word interface document filled in S8 with a version number;

[0017] S10: Determine whether the Word interface document with the version number named by S9 is on the minio. If so, replace it. Otherwise, upload the Word interface document to minio and obtain a download link.

[0018] S11: providing the download link obtained in S10 to a partner who needs to connect, and the partner only needs to refresh to download the latest version of the Word interface document according to demand.

[0019] Preferably, the Word interface document includes the following interface dynamic data: method name {title}, method description {desc}, request path {path}, request parameters {paramList}, request example {requestDemo}, response parameters {responseList}, request method {requestType}, and group name {groupName}.

[0020] Preferably, all the API interface data of the openapi specification in S5 are in JSON format.

[0021] A system for generating a custom API document includes a memory and a processor, wherein the memory stores executable commands of the processor; and the processor is configured to implement any of the above-mentioned methods by executing the executable commands.

[0022] A computer-readable storage medium stores a computer program, which, when executed by a processor, implements any of the methods described above.

[0023] By adopting the above-mentioned design scheme, the beneficial effect of the present invention is as follows: the present invention adopts an automated process to automatically extract all API interface data of the OpenAPI specification from the API interface provided by Swagger, and then automatically fills the obtained API interface data into a customized Word interface document, eliminating the tediousness of traditional manual document filling, while also improving the efficiency and accuracy of document generation. BRIEF DESCRIPTION OF THE DRAWINGS

[0024] Figure 1 A Word interface document customized for the present invention;

[0025] Figure 2 The final Word interface document obtained by the present invention;

[0026] Figure 3 Flow chart of the method of the present invention. DETAILED DESCRIPTION

[0027] The following is a clear and complete description of the technical solutions in the embodiments of the present invention, in conjunction with the accompanying drawings. Obviously, the described embodiments are only part of the embodiments of the present invention, not all of the embodiments. All other embodiments obtained by ordinary technicians in this field based on the embodiments of the present invention without making any creative efforts are within the scope of protection of the present invention.

[0028] The method for generating custom API documentation based on Swagger and Word includes the following steps:

[0029] S1: Define a Word interface document. Dynamic interface data in the Word interface document is replaced with placeholders and transmitted to minio. In this embodiment, the Word interface document includes the following dynamic interface data: method name {title}, method description {desc}, request path {path}, request parameters {paramList}, request example {requestDemo}, response parameters {responseList}, request method {requestType}, and group name {groupName}. In actual use, this dynamic interface data can be customized to generate a Word interface document that meets specific requirements, providing greater flexibility and adaptability.

[0030] S2: Introduce swagger-related dependency packages into the system project and configure the project path that swagger needs to scan. The file format of the dependency package in this embodiment is springfox-swagger2.2.9.2.jar.

[0031] S3: When developing the interface of the system engineering, fill in the API interface data defined by the swagger framework; the API interface data includes the method name, method description, request path, request parameters, response parameters, request method, and group name of the API interface parameters.

[0032] S4: When the system project is started, Swagger automatically scans all API interface data on the system project, and encapsulates the API interface data into data in the apenapi standard format and provides the corresponding API interface to the outside world;

[0033] S5: Call the API interface provided by swagger and obtain all API interface data of the openapi specification through an http request; in this embodiment, all API interface data of the openapi specification are in JSON format.

[0034] S6: Extract the required API interface data from all the API interface data generated in S5, filter out the API interfaces that do not need to be provided to the outside based on the API interface data, and store the extracted API interface data in the system engineering for subsequent processing; in this embodiment, filter out the API interfaces that do not need to be provided to the outside based on the group name.

[0035] S7: Download the Word interface document defined in S1 through minio;

[0036] S8: Use the open source Apache POI library to operate the Word interface document downloaded in S7, and fill the API interface data extracted in S6 into the corresponding position in the Word interface document; by automatically extracting the API interface data in the sagger specification and filling it into the customized Word interface document, the tedious process of manual document writing is avoided, and efficiency is improved.

[0037] S9: After the Word interface document data is filled, the Word interface document filled in S8 is named with the version number; through automated filling and updating, the consistency of the Word interface document is improved, which helps to ensure that the information in the Word interface document is synchronized with the actual API in real time, reducing the risk of information inconsistency.

[0038] S10: Determine whether there is a Word interface document with the version number named by S9 on minio. If so, replace it. Otherwise, upload the Word interface document to minio and obtain a download link. The automatic generation of the Word interface document reduces the maintenance cost of the document. Developers do not need to maintain the document manually, which reduces the workload and ensures timely updates.

[0039] S11: Provide the download link obtained in S10 to the partner who needs to connect. The partner only needs to refresh to download the corresponding latest version of the Word interface document according to demand.

[0040] This embodiment also provides a system for implementing the above method.

[0041] A system for generating a custom API document includes a memory and a processor, wherein the memory stores executable commands of the processor; and the processor is configured to implement any of the above-mentioned methods by executing the executable commands.

[0042] This embodiment also provides a storage medium storing a computer program for implementing the above method.

[0043] A computer-readable storage medium stores a computer program, which, when executed by a processor, implements any of the methods described above.

[0044] In summary, the present invention adopts an automated process to automatically extract all API interface data of the OpenAPI specification from the API interface provided by Swagger, and then automatically fills the obtained API interface data into a customized Word interface document, eliminating the tediousness of traditional manual document filling and improving the efficiency and accuracy of document generation.

[0045] While embodiments of the present invention have been shown and described, it will be appreciated by those skilled in the art that various changes, modifications, substitutions, and variations may be made to these embodiments without departing from the principles and spirit of the invention, and that the scope of the invention is defined by the appended claims and their equivalents.

Claims

1. A method for generating custom API documents based on swagger and word, characterized by: The process includes the following steps: S1: Define a Word interface document, in which the interface dynamic data is replaced with placeholders and transmitted to minio; S2: Introduce swagger-related dependency packages into the system engineering and configure the project path that swagger needs to scan; S3: When developing the interface of the system engineering, fill in the API interface data defined by the swagger framework; S4: When the system project is started, Swagger automatically scans all the API interface data on the system project, and respectively encapsulates the API interface data into data in the OpenAPI standard format and provides the corresponding API interface to the outside world; S5: Call the API interface provided by Swagger and obtain all the API interface data specified in the OpenAPI specification through an HTTP request; S6: extracting required API interface data from all the API interface data obtained in S5, filtering out unnecessary API interface data, and storing the filtered API interface data in the system engineering for subsequent processing; S7: Download the Word interface document defined in S1 through minio; S8: Use the open source Apache POI library to operate the Word interface document downloaded in S7, and fill the API interface data stored in the system project in S6 into the corresponding position in the Word interface document; S9: Name the Word interface document filled in S8 with a version number; S10: Determine whether the Word interface document with the version number named by S9 is on the minio. If so, replace it. Otherwise, upload the Word interface document to minio and obtain a download link. S11: providing the download link obtained in S10 to a partner who needs to connect, and the partner only needs to refresh to download the latest version of the Word interface document according to demand.

2. The method for generating a custom API document based on Swagger and Word according to claim 1, characterized in that: The Word interface document includes the following interface dynamic data: method name, method description, request path, request parameters, request example, response parameters, request method, and group name.

3. The method for generating a custom API document based on Swagger and Word according to claim 1, characterized in that: All the API interface data in the OpenAPI specification in S5 is in JSON format.

4. A system for generating custom API documents, characterized by: The method comprises a memory and a processor, wherein the memory stores executable instructions of the processor; and the processor is configured to implement the method according to any one of claims 1 to 3 by executing the executable instructions.

5. A computer-readable storage medium having a computer program stored thereon, characterized in that: When the program is executed by a processor, the method according to any one of claims 1 to 3 is implemented.

Images