Centralized document collection and management method based on OpenAPI specification
By using Master and Slave nodes to allocate acquisition tasks in the OpenAPI acquisition management center, the centralized management problem of OpenAPI documents in a distributed environment is solved, and the historical version storage and offline export of documents are realized, meeting the needs of API consumers in the intranet environment , improve management efficiency.
Patent Information
- Application Number
- CN202411211117.4
- Authority / Receiving Office
- CN · China
- Patent Type
- Applications(China)
- Current Assignee / Owner
- Filing Date
- 2024-08-30
- Publication Date
- 2025-01-10
AI Technical Summary
In a distributed multi-instance deployment environment, OpenAPI documents are difficult to centrally manage, cannot view historical changes in real time, and cannot be exported and accessed offline, especially in intranet environments, three-party API consumers cannot directly access it.
Set up the OpenAPI acquisition management center, assign collection tasks through the Master node and the Slave node, select the master using the Raft protocol, and the Slave node collects OpenAPI documents and stores historical versions, supports offline export and independent deployment, and provides a unified management platform.
It realizes centralized collection and management of multi-instance OpenAPI documents, allows three-party users to view and export documents, store historical versions, supports offline use and independent deployment, and improves document accessibility and management efficiency.
Smart Images
Figure CN119299442A_ABST
Abstract
Description
Technical Field
[0001] The present invention belongs to the field of computer technology, and in particular relates to a centralized document collection and management method based on the OpenAPI specification. Background Art
[0002] OpenAPI stands for OpenAPI Specification (OSA for short), which uses a specified format to describe the definition of HTTP RESTful API, thereby standardizing the RESTful service development process. Use JSON or YAML to describe a standard HTTP API interface that is independent of programming languages. The OpenAPI specification was originally based on the Swagger specification donated by SmartBearSoftware in 2015, and the latest version is v3.x. In short, OpenAPI is a specification for defining HTTP interface documents. Everyone writes interface documents according to the same set of specifications, which can greatly reduce communication costs.
[0003] There are generally two ways to describe an Http Restful API interface through an OpenAPI specification document. One is to manually write an OpenAPI specification document based on the functions and specifications of the interface. The other is to use the code-as-document method and use some tools provided by swagger to automatically generate OpenAPI documents for the RestfulAPI code in the project.
[0004] At present, many Java frameworks can integrate the Swagger tool (https: / / swagger.io / ) to expose the RESTful interface of the developed business code through the OpenAPI specification. In this way, other third-party users can quickly understand how to use the business API interface in our project (such as viewing the interface description, input and output parameters, calling methods, etc.) by viewing the OpenAPI interface document exposed by the project.
[0005] For example, a typical usage method is: through the SpringBoot+springfox framework or the SpringBoot+springDoc framework, you can automatically generate an OpenAPI document for the business Restful API by adding specific Java annotations to the Spring Controller interface. The document describes the business interface, the input and output parameters of the business interface, the business interface calling method, etc., and can be conveniently provided to consumers of the business API interface for viewing and use.
[0006] The method of automatically generating OpenAPI specification documents for business RESTful API codes through Java framework + Swagger tool can well solve the problem of automatic generation of OpenAPI documents for a single project. However, in the actual environment, there are the following problems:
[0007] (1) In actual production environments, application projects are deployed in distributed multi-instance configurations. If you want to view the OpenAPI document of a business, you need to locate a specific application instance address to view its exposed OpenAPI document. In actual deployment, the instance address may change constantly (for example, when deployed in a Kubernetes environment). Therefore, you need to configure some fixed domain name mappings to map the OpenAPI access address to a fixed application instance. However, when the application instance goes down, the OpenAPI document will also be inaccessible.
[0008] (2) The application instance exposes the real-time OpenAPI specification document of the currently deployed code, and it is impossible to view the historical changes of OpenAPI.
[0009] (3) OpenAPI documents cannot be viewed and exported offline. For example, all application instances are deployed in the intranet environment, and third-party API consumers cannot connect to the intranet environment to directly access OpenAPI documents. It is necessary to provide an OpenAPI environment that can be accessed by third-party API consumers in an offline and independent manner, and provide an OpenAPI document export function. Summary of the invention
[0010] In response to the above problems, the present invention proposes a centralized document collection and management method based on the OpenAPI specification. A special OpenAPI collection management center is set up. Through a certain collection strategy, an instance is selected from a business application deployed by multiple instances, its OpenAPI specification document is collected, and its different historical versions are stored according to the trajectory of content changes.
[0011] To achieve the above objectives, the present invention discloses a centralized document collection and management method based on the OpenAPI specification, comprising:
[0012] Manage node configuration or automatically discover cluster collection information based on OpenAPI, including instance information of the collected application and collection frequency information, and store it in the database;
[0013] A Master node is selected within the OpenAPI collection node cluster, and the Master node reads the cluster collection information in the database;
[0014] The Master node allocates the application instances to be collected to each Slave node according to the number of application instances to be collected in the cluster collection information and the number of Slave nodes in the OpenAPI collection node cluster, and synchronizes the instance information and collection frequency information of the application instances to be collected to the corresponding Slave nodes;
[0015] The slave node calls the HTTP interface of the application instance to be collected and collects the OpenAPI documents of the application instance to be collected according to the collection frequency;
[0016] The Slave node queries the database based on the summary information of the OpenAPI document. If the same summary information exists, the current collection is terminated. If the same summary information does not exist, the current OpenAPI document, summary information, and timestamp are stored in the database.
[0017] As a further improvement of the present invention, it is characterized in that:
[0018] For application clusters deployed in bare metal, physical machine or virtual machine environments, configure the corresponding cluster collection information based on the OpenAPI management node and store it in the database;
[0019] For application clusters deployed in the Kubernetes container environment, the OpenAPI management node automatically discovers the workload in the Kubernetes namespace to automatically discover the applications and instance information deployed in the namespace, save them to the database, and maintain the application and instance information in real time in the database.
[0020] As a further improvement of the present invention, the OpenAPI collection node cluster performs internal leader election through the Raft protocol to select the Master node.
[0021] As a further improvement of the present invention, the Master node reads the cluster collection information in the database, including: the address of the application instance to be collected, the Http path to be collected, and the collection frequency.
[0022] As a further improvement of the present invention, each Slave node is assigned an application instance to be collected, including:
[0023] Through a certain algorithm, the applications to be collected are evenly distributed to each Slave node to form an application instance list.
[0024] As a further improvement of the present invention, the Slave node collects the OpenAPI document of the application instance to be collected according to the collection frequency by calling the Http interface of the application instance to be collected; including:
[0025] After the Slave node receives the list of applications to be collected from the Master, it selects one of the multiple instances of the application for collection according to a certain algorithm, obtains the specific OpenAPI document collection address (IP / Port), collects the Http path, and collects the OpenAPI document of the corresponding instance by calling the application instance Http interface within a certain time period according to the configured collection frequency.
[0026] As a further improvement of the present invention, the Slave node calculates the summary information of the OpenAPI document through the SHA-256 algorithm.
[0027] As a further improvement of the present invention, third-party users who consume the Restful interface can query the OpenAPI document information of the Restful interface and its historical track change information through the OpenAPI management node.
[0028] As a further improvement of the present invention, the OpenAPI management node provides relevant Http interface testing tools, which can generate test content of relevant interfaces with one click according to the OpenAPI specification document.
[0029] As a further improvement of the present invention, the OpenAPI collection node cluster and the OpenAPI management node support independent isolation deployment;
[0030] Deploy the OpenAPI collection node cluster and the application cluster together. After the OpenAPI collection node cluster collects the OpenAPI document, it exports the offline file in the form of a file.
[0031] In another independent environment, deploy an OpenAPI management node separately and import the offline file through the OpenAPI management node.
[0032] Compared with the prior art, the present invention has the following beneficial effects:
[0033] The present invention can collect the OpenAPI documents exposed by the application cluster, collect the OpenAPI documents scattered in each cluster and each application instance, and manage them in a centralized manner. Third-party users or administrators can manage and view related Restful interface documents and debug them through a unified OpenAPI management platform. At the same time, the historical version track of the OpenAPI document of a Restful interface is stored, so that the historical version changes of the interface can be easily viewed. BRIEF DESCRIPTION OF THE DRAWINGS
[0034] Figure 1A schematic diagram of the structure of a centralized document collection and management method based on the OpenAPI specification disclosed in an embodiment of the present invention;
[0035] Figure 2 A schematic diagram of displaying collected OpenAPI document information disclosed in an embodiment of the present invention. DETAILED DESCRIPTION
[0036] In order to make the purpose, technical solution and advantages of the embodiments of the present invention clearer, the technical solution in the embodiments of the present invention will be clearly and completely described below in conjunction with the drawings in the embodiments of the present invention. Obviously, the described embodiments are part of the embodiments of the present invention, not all of the embodiments. Based on the embodiments of the present invention, all other embodiments obtained by ordinary technicians in this field without creative work are within the scope of protection of the present invention.
[0037] The present invention is further described in detail below in conjunction with the accompanying drawings:
[0038] like Figure 1 As shown, the present invention discloses a centralized document collection and management method based on the OpenAPI specification, including:
[0039] S1. Manage node configuration or automatically discover cluster collection information based on OpenAPI, including instance information (IP, Port, Path) of the collected application and collection frequency information, and store them in the database;
[0040] in,
[0041] For application clusters deployed in bare metal, physical machine or virtual machine environments, configure the corresponding cluster collection information based on the OpenAPI management node and store it in the database;
[0042] For application clusters deployed in the Kubernetes container environment, the OpenAPI management node automatically discovers the workload in the Kubernetes namespace to automatically discover the applications and instance information deployed in the namespace, save them to the database, and maintain the application and instance information in real time in the database.
[0043] S2. The OpenAPI collection node cluster selects a Master node, which reads the cluster collection information in the database.
[0044] in,
[0045] The OpenAPI collection node cluster uses the Raft protocol to select an internal leader and select the Master node.
[0046] Furthermore,
[0047] The Master node reads the cluster collection information in the database, including: the address of the application instance to be collected, the Http path to be collected, and the collection frequency.
[0048] S3. The Master node allocates the application instances to be collected to each Slave node according to the number of application instances to be collected in the cluster collection information and the number of Slave nodes in the OpenAPI collection node cluster, and synchronizes the instance information and collection frequency information of the application instances to be collected to the corresponding Slave nodes;
[0049] in,
[0050] Through a certain algorithm, the applications to be collected are evenly distributed to each Slave node to form an application instance list.
[0051] Furthermore,
[0052] The default is an even distribution method. For example, if there are 10 applications to be collected and 2 Slave nodes, 5 applications to be collected will be allocated to each Slave node. Subsequently, the relevant application information to be collected will be synchronized to the Slave node.
[0053] S4, the slave node calls the Http interface of the application instance to be collected, and collects the OpenAPI document of the application instance to be collected according to the collection frequency;
[0054] in,
[0055] After the Slave node receives the list of applications to be collected from the Master synchronization, it selects one of the multiple instances of the application for collection according to a certain algorithm (random selection by default), obtains the specific OpenAPI document collection address (IP / Port), collects the Http path, and collects the OpenAPI document of the corresponding instance by calling the application instance Http interface within a certain time period (Cron method) according to the configured collection frequency.
[0056] S5. The slave node queries the database based on the summary information of the OpenAPI document. If the same summary information exists, the current collection is terminated. If the same summary information does not exist, the current OpenAPI document, summary information, and timestamp are stored in the database.
[0057] in,
[0058] The slave node calculates the summary information of the OpenAPI document using the SHA-256 algorithm;
[0059] The timestamp is stored in the database as version information, so that the historical version information of the OpenAPI changes will be continuously stored in the database.
[0060] In the present invention, third-party users who need to consume the Restful interface can query the OpenAPI document information of the Restful interface and its historical track change information through the OpenAPI management node, and display it to the third-party users in a user-friendly visual manner.
[0061] In the present invention, the OpenAPI management node provides relevant Http interface testing tools, which can generate the test content of the relevant interface with one click according to the OpenAPI specification document, making it convenient for users to perform interface testing and joint debugging.
[0062] In the present invention, the OpenAPI collection node cluster and the OpenAPI management node support independent and isolated deployment; that is: the OpenAPI collection node cluster and the application cluster are deployed together, and after the OpenAPI collection node cluster collects the OpenAPI document, the offline file is exported in the form of a file; in another independent environment, the OpenAPI management node is deployed separately, and the offline file is imported through the OpenAPI management node.
[0063] In the present invention, the system administrator role is configured: the relevant information of the application cluster to be collected can be configured through the management interface, including the address (ip, port) of the application instance, the Http Path of the OpenAPI document, the collection frequency (Cron expression) of the document, etc. After the configuration is completed, the collection node will collect the OpenAPI document of the application regularly according to the configured collection strategy and at a certain time frequency.
[0064] The present invention configures the role of the three-party interface consumer: after logging in to the management node, you can view the OpenAPI document of the application's Restful interface according to your authority. Through the OpenAPI document, you can understand the call address, Http request method, input and output parameter information, etc. of the interface, and you can view the historical track change information of the interface. In addition, you can also call and test the interface directly on the management platform.
[0065] Advantages of the present invention:
[0066] The collection node cluster of the present invention will select a master through the Raft protocol, and then uniformly allocate collection tasks to each node through the selected Master node, and can also flexibly adjust the task allocation algorithm. In this way, when the application cluster to be collected is particularly large, a very high collection efficiency can be achieved by expanding the collection nodes.
[0067] The management node of the OpenAPI of the present invention is separated from the collection node cluster. By deploying the collection node cluster to different environments, OpenAPI documents of multiple different application clusters can be collected and uniformly managed, displayed and used through the management node.
[0068] After the present invention periodically collects OpenAPI documents through the configured collection frequency, it will calculate the digest of the document through the SHA-256 digest algorithm, and compare it with the OpenAPI digest already existing in the database. If there is a change, the latest version will be stored in the database, thereby forming a historical track version storage of the OpenAPI document.
[0069] The collection node of the present invention can export the stored OpenAPI document data in a certain format, and the management node can import these offline OpenAPI document data and display them.
[0070] The above are only preferred embodiments of the present invention and are not intended to limit the present invention. For those skilled in the art, the present invention may have various modifications and variations. Any modification, equivalent replacement, improvement, etc. made within the spirit and principle of the present invention shall be included in the protection scope of the present invention.
Claims
1. A centralized document collection and management method based on OpenAPI specification, characterized in that: include: Manage node configuration or automatically discover cluster collection information based on OpenAPI, including instance information of the collected application and collection frequency information, and store it in the database; A Master node is selected within the OpenAPI collection node cluster, and the Master node reads the cluster collection information in the database; The Master node allocates the application instances to be collected to each Slave node according to the number of application instances to be collected in the cluster collection information and the number of Slave nodes in the OpenAPI collection node cluster, and synchronizes the instance information and collection frequency information of the application instances to be collected to the corresponding Slave nodes; The slave node calls the HTTP interface of the application instance to be collected and collects the OpenAPI documents of the application instance to be collected according to the collection frequency; The Slave node queries the database based on the summary information of the OpenAPI document. If the same summary information exists, the current collection is terminated. If the same summary information does not exist, the current OpenAPI document, summary information, and timestamp are stored in the database.
2. The centralized document collection and management method based on the OpenAPI specification according to claim 1 is characterized in that: For application clusters deployed in bare metal, physical machine or virtual machine environments, configure the corresponding cluster collection information based on the OpenAPI management node and store it in the database; For application clusters deployed in the Kubernetes container environment, the OpenAPI management node automatically discovers the workload in the Kubernetes namespace to automatically discover the applications and instance information deployed in the namespace, save them to the database, and maintain the application and instance information in real time in the database.
3. The centralized document collection and management method based on the OpenAPI specification according to claim 1 is characterized in that: The OpenAPI collection node cluster uses the Raft protocol to select an internal leader and select the Master node.
4. The centralized document collection and management method based on the OpenAPI specification according to claim 1 is characterized in that: The master node reads the cluster collection information in the database, including: the address of the application instance to be collected, the Http path to be collected, and the collection frequency.
5. The centralized document collection and management method based on the OpenAPI specification according to claim 1 is characterized in that: Assign application instances to be collected to each slave node, including: Through a certain algorithm, the applications to be collected are evenly distributed to each Slave node to form an application instance list.
6. The centralized document collection and management method based on the OpenAPI specification according to claim 1 is characterized in that: The slave node collects OpenAPI documents for the application instance to be collected according to the collection frequency by calling the Http interface of the application instance to be collected; including: After the Slave node receives the list of applications to be collected from the Master synchronization, it selects one of the multiple instances of the application for collection according to a certain algorithm, obtains the specific OpenAPI document collection address, collects the Http path, and collects the OpenAPI document of the corresponding instance by calling the application instance Http interface within a certain time period according to the configured collection frequency.
7. The centralized document collection and management method based on the OpenAPI specification according to claim 1 is characterized in that: The slave node calculates the summary information of the OpenAPI document using the SHA-256 algorithm.
8. The centralized document collection and management method based on the OpenAPI specification according to claim 1 is characterized in that: Third-party users who consume the Restful interface can query the OpenAPI document information of the Restful interface and its historical track change information through the OpenAPI management node.
9. The centralized document collection and management method based on the OpenAPI specification according to claim 1, characterized in that: The OpenAPI management node provides relevant Http interface testing tools, which can generate test content of relevant interfaces with one click according to the OpenAPI specification document.
10. The centralized document collection and management method based on the OpenAPI specification according to claim 1, characterized in that: The OpenAPI collection node cluster and the OpenAPI management node support independent isolation deployment; Deploy the OpenAPI collection node cluster and the application cluster together. After the OpenAPI collection node cluster collects the OpenAPI document, it exports the offline file in the form of a file. In another independent environment, deploy an OpenAPI management node separately and import the offline file through the OpenAPI management node.