Compatibility aggregation method and system for multi-source heterogeneous micro-service api document

Abstract

This invention provides a compatible aggregation method and system for multi-source heterogeneous microservice API documents. The system includes a multi-channel service discovery module, a specification detection and version identification module, a heterogeneous document conversion engine, an aggregation storage and caching module, and a version-aware front-end display module. The method includes the following sub-steps: S1: Parallel execution of service collection operations to obtain service instance information; S2: Interface description document version detection and specification identification; S3: Unified conversion of heterogeneous interface documents; S4: Aggregation storage and caching; S5: Client data display and interface retrieval. This method accesses unregistered services through static configuration and manual registration. It is suitable for legacy systems not connected to the registry center, external third-party services, and temporary services in the development environment. It achieves low-intrusion access without modifying service code, deploying additional proxies, or adjusting the network architecture.

Description

Technical Field

[0001] This invention relates to the field of microservice architecture and open platform technology, and in particular to a method and system for compatible aggregation of API documents for multi-source heterogeneous microservices. Background Technology

[0002] In the fields of microservice architecture and open platform technology, enterprises typically expose the application programming interfaces (APIs) of multiple backend microservices to third-party developers through a unified open platform portal. To reduce the learning and integration costs for developers, the open platform portal needs to automatically collect the interface documentation of each backend microservice and display it centrally. The current mainstream API documentation standard in the industry is the OpenAPI specification. This specification has undergone several version evolutions and is mainly divided into two categories: one is Swagger 1.0 / 2.0, corresponding to OpenAPI 1.0 / 2.0, which is an early and widely used version, using the swagger field as the root node identifier; the other is OpenAPI 3.0, which is the current mainstream version, using the openapi field as the root node identifier, and has made significant improvements in parameter expression and component reuse. At the technical implementation level, different microservice development frameworks support the OpenAPI specification in different ways: Spring Boot 1.x typically integrates Swagger 1.0 / 2.0 dependencies, exposing the / v2 / api-docs endpoint; Spring Boot 2.x can support either Swagger 2.0 (springfox) or OpenAPI 3.0 (springdoc), exposing either the / v2 / api-docs or / v3 / api-docs endpoint; Spring Boot 3.x and above natively support OpenAPI 3.0, exposing the / v3 / api-docs endpoint. At the service discovery level, there are various heterogeneous registry center implementations in the industry: Eureka is an open-source component from Netflix, widely used in the Spring Boot 1.x / 2.x ecosystem; Nacos is open-source from Alibaba, adapted to the Spring Cloud Alibaba ecosystem, and has better compatibility with Spring Boot 3.x; Consul is open-source from HashiCorp, supporting multiple technology stacks; in addition, there are scenarios without a registry center, where services are directly proxied by ELB.

[0003] Existing API documentation aggregation solutions mostly rely on registry centers to obtain service addresses and collect documentation, which is difficult to adapt to the complex environments of enterprises with multiple registry centers, multiple specification versions, and some services not being registered; specifically, they have the following drawbacks: Assuming all microservices are registered and can be discovered uniformly, it is not possible to support the access of unregistered services: Existing technology assumes that all services are registered in the same registry or service bus and are visible to the portal. However, in actual enterprises, some legacy systems are not registered to any registry due to network isolation and security policies. External third-party services cannot access the internal registry, and services from different teams may be scattered across different registry instances, resulting in unregistered services not being discovered and documentation not being collected. Unable to handle registry incompatibility issues: Enterprises commonly have multiple generations of heterogeneous registry centers such as Eureka and Nacos coexisting. Their protocols and implementations are incompatible with each other. Existing technologies rely on a single registry center or require cross-center data synchronization, which not only increases system complexity due to additional development, but also causes synchronization delays and poor real-time performance. Some enterprises even prohibit direct communication between different registry centers, ultimately making it impossible to uniformly discover services from multiple registry centers. Summary of the Invention

[0004] The purpose of this invention is to address the shortcomings of existing technologies by proposing a compatible aggregation method and system for multi-source heterogeneous microservice API documents.

[0005] To achieve the above objectives, the present invention adopts the following technical solution: A compatible aggregation system for multi-source heterogeneous microservice API documents, the system includes a multi-channel service discovery module, a specification detection and version identification module, a heterogeneous document conversion engine, an aggregation storage and caching module, and a version-aware front-end display module; The multi-channel service discovery module is used to collect service instance information from multiple heterogeneous sources in parallel and label the source identifiers; The specification detection and version identification module is used to traverse service instance information and detect interface documents to identify OpenAPI 3.0 and Swagger 2.0 specification versions; The heterogeneous document conversion engine matches the corresponding document conversion adapter according to the recognition result, extracts the information of the interface description document, and uniformly encapsulates it into a preset intermediate data model. The aggregation storage and caching module is used to cache a unified intermediate data model, establish indexes, and implement incremental updates. The version-aware front-end display module is used to display service and interface information, label the source and specification version, and supports cross-service search; This invention also proposes a compatible aggregation method for API documents of multi-source heterogeneous microservices, including the following sub-steps: S1: Perform service collection operations in parallel to obtain service instance information; The open platform portal is launched, and the multi-channel service discovery module performs service collection operations in parallel, simultaneously obtaining service instance information from multiple heterogeneous sources; and the service instance information is labeled with the corresponding source identifier. The service collection operations include pulling Eureka registry service, pulling Nacos registry service, parsing static configuration file service, and obtaining manual registration service; Each service instance information includes the service name, service address, port number, etc. All service instance information from the multi-channel discovery module is aggregated, and the service instance information is compared using the service name + service address as the unique key value. Service instance information with duplicate key values ​​is removed, and the retained service instance information is saved to a list to form a service instance information list.

[0006] S2: Interface description document version detection and specification identification; The specification detection and version identification module sequentially traverses each service instance information in the service instance information list, and concatenates the service address and port number in each service instance information to obtain the service access address; An HTTP request is sent to the OpenAPI 3.0 interface corresponding to the service access address after concatenation. If the response status code is 200, the interface description document returned by the OpenAPI 3.0 interface is parsed. If the interface description document contains the openapi field and starts with "3.", it is identified as the OpenAPI 3.0 specification version and the interface description document is stored. If the response status code is not 200, proceed with the following probe directly; If the response status code is 200, and the `openapi` field does not exist in the API description document or does not begin with "3.", then the following probes are performed: An HTTP request is sent to the Swagger 2.0 interface corresponding to the concatenated service access address. If the response status code is 200, the interface description document returned by the Swagger 2.0 interface is parsed. If the interface description document contains a swagger field and starts with "2.", it is identified as a Swagger 2.0 specification version and the interface description document is stored. If the response status code is not 200, or the interface description document does not contain a swagger field or the swagger field does not start with "2.", the service instance information is marked as having an abnormal interface description document.

[0007] S3: Unified conversion of heterogeneous interface documents; The heterogeneous document conversion engine calls the corresponding document conversion adapter based on the OpenAPI 3.0 specification version and Swagger 2.0 specification version identified in step S2; The document conversion adapter parses the interface description document corresponding to each service instance information and extracts the document data. The document data includes the service name, source identifier, specification version, interface list, and interface entity data structure. The interface list includes information such as access path, request method, and request parameters. Each service instance information is encapsulated into a unified intermediate data model (to normalize the format of heterogeneous documents between Swagger 2.0 and OpenAPI 3.0). After all services are encapsulated, a unified intermediate data model list is formed.

[0008] S4: Aggregated storage and caching; The aggregation storage and caching module synchronously saves the encapsulated unified intermediate data model to the memory cache, constructs key-value pairs with the service name as the key and the document data as the value, establishes a cache mapping, and sets the cache expiration time. Simultaneously save document data to an external database and build an index based on the source identifier and access path; For service instance information changes from the registry center, the interface description document is periodically retrieved for service instance information from both static configuration and manual registration sources. The MD5 algorithm is used to calculate the hash value of the interface description document and compare it with the hash value in the memory cache. Only when the hash values ​​are inconsistent, the corresponding document data in the memory cache and the external database are refreshed.

[0009] S5: Client-side data display and interface retrieval; The frontend calls the aggregated document interface provided by the backend to obtain a unified intermediate data model list, extracts information such as the interface list, service name, source identifier, and specification version, and displays it on the service list page of the version-aware frontend display module; it displays the corresponding access path, request method, request parameters, and other information, and marks the service source and specification version to which the interface belongs; it also supports cross-service search for all services.

[0010] Compared with the prior art, the beneficial effects of the present invention are as follows: This method enables low-intrusion access to unregistered services through static configuration and manual registration. It is suitable for legacy systems not connected to the registry center, external third-party services, and temporary services in the development environment. It does not require modification of service code, deployment of additional proxies, or adjustment of network architecture. By proactively connecting to multiple heterogeneous registry centers such as Eureka and Nacos through the portal and independently pulling service lists, all services can be discovered uniformly without data synchronization between registry centers; and the failure of any registry center does not affect the service pulling of other registry centers, significantly improving system availability. Attached Figure Description

[0011] Figure 1This is a flowchart illustrating the steps of the compatible aggregation method for multi-source heterogeneous microservice API documents according to the present invention. Detailed Implementation

[0012] To provide a further understanding of the purpose, structure, features, and functions of the present invention, detailed descriptions are provided below with reference to specific embodiments.

[0013] This invention proposes a compatible aggregation system for multi-source heterogeneous microservice API documents. The system includes a multi-channel service discovery module, a specification detection and version identification module, a heterogeneous document conversion engine, an aggregation storage and caching module, and a version-aware front-end display module. The multi-channel service discovery module is used to collect service instance information from multiple heterogeneous sources in parallel and label the source identifiers; The specification detection and version identification module is used to traverse service instance information and detect interface documents to identify OpenAPI 3.0 and Swagger 2.0 specification versions; The heterogeneous document conversion engine matches the corresponding document conversion adapter according to the recognition result, extracts the information of the interface description document, and uniformly encapsulates it into a preset intermediate data model. The aggregation storage and caching module is used to cache a unified intermediate data model, establish indexes, and implement incremental updates. The version-aware front-end display module is used to display service and interface information, indicate the source and specification version, and support cross-service search.

[0014] like Figure 1 As shown, this invention also proposes a compatible aggregation method for API documents of multi-source heterogeneous microservices, including the following sub-steps: S1: Perform service collection operations in parallel to obtain service instance information; The open platform portal is launched, and the multi-channel service discovery module performs service collection operations in parallel, simultaneously obtaining service instance information from multiple heterogeneous sources; and the service instance information is labeled with the corresponding source identifier. The service collection operations include pulling Eureka registry service, pulling Nacos registry service, parsing static configuration file service, and obtaining manual registration service; The service instance information includes service name, service address, port number, etc. Specifically, the Eureka registry service is retrieved: the multi-channel service discovery module sends an HTTP request to the Eureka registry, calls the GET / eureka / apps interface to obtain the list of registered services, which is in XML or JSON format; the service list is parsed to obtain service instance information, which includes service name, IP address, port number, etc.; and the service instance is marked with the source identifier serviceSource = "eureka"; Retrieve Nacos Registry Services: The multi-channel service discovery module initiates an HTTP GET request to the Nacos Registry, calling the GET / nacos / v1 / ns / instance / list interface to retrieve the list of registered services, which is in JSON format; it parses the service list to obtain service instance information, including service name, IP address, port number, etc.; and it marks the service instance with the source identifier serviceSource = "nacos"; Parsing static configuration file service: The multi-channel service discovery module reads the configuration information under the portal.static-services node in the project configuration file application.yml, extracts service instance information such as service name, service access address, and API documentation endpoint, and marks the service instance information with the source identifier serviceSource = "static-config"; Obtaining manual registration service: The multi-channel service discovery module receives service instance information such as service name, service access address, and API documentation endpoint from external sources through the HTTP POST / api / manual / register interface provided by the open platform portal; it performs format validation and connectivity validity verification on the service address, and marks the service instance information with the source identifier serviceSource = "manual" after the verification is passed; Furthermore, for legacy systems, external third-party services, or temporary test services that are not registered with any service discovery center (such as Eureka, Nacos, Consul, etc.), basic information about the service is described through a declarative configuration file (YAML or JSON format). The open platform portal parses the configuration file at startup or runtime and automatically includes the configured service in the unified service list, thereby achieving zero-intrusion access without modifying any code, deploying any proxy, or altering the network architecture.

[0015] S2: Interface document version detection and specification identification; The specification detection and version identification module sequentially traverses each service instance information in the service instance information list, and concatenates the service address and port number in each service instance information to obtain the service access address; An HTTP request is sent to the OpenAPI 3.0 interface corresponding to the service access address after concatenation. If the response status code is 200, the interface description document returned by the OpenAPI 3.0 interface is parsed. If the interface description document contains the openapi field and starts with "3.", it is identified as the OpenAPI 3.0 specification version and the interface description document is stored. If the response status code is not 200, proceed with the following probe directly; If the response status code is 200, and the `openapi` field does not exist in the API description document or does not begin with "3.", then the following probes are performed: An HTTP request is sent to the Swagger 2.0 interface corresponding to the concatenated service access address. If the response status code is 200, the interface description document returned by the Swagger 2.0 interface is parsed. If the interface description document contains a swagger field and starts with "2.", it is identified as a Swagger 2.0 specification version and the interface description document is stored. If the response status code is not 200, or the interface description document does not contain a swagger field or the swagger field does not start with "2.", the service instance information is marked as an interface description document exception (OPENAPI-ERROR).

[0016] S3: Unified conversion of heterogeneous interface documents; The heterogeneous document conversion engine calls the corresponding document conversion adapter based on the OpenAPI 3.0 specification version and Swagger 2.0 specification version identified in step S2; Specifically: when the specification version of the interface description document is OpenAPI 3.0, the OpenAPI 3.0 document transformation adapter is invoked; when the specification version of the interface description document is Swagger 2.0, the Swagger 2.0 document transformation adapter is invoked. The document conversion adapter parses the interface description document corresponding to each service instance information and extracts the document data. The document data includes the service name, source identifier, specification version, interface list, and interface entity data structure. The interface list includes information such as access path, request method, and request parameters. Each service instance information is encapsulated into a unified intermediate data model to normalize the format of heterogeneous documents between Swagger 2.0 and OpenAPI 3.0. After all services are encapsulated, a unified intermediate data model list is formed.

[0017] S4: Aggregated storage and caching; The aggregation storage and caching module synchronously saves the encapsulated unified intermediate data model to the memory cache, constructs key-value pairs with the service name as the key and the document data as the value, establishes a cache mapping, and sets the cache expiration time. Simultaneously save document data to an external database and build an index based on the source identifier and access path; For service instance information changes from the registry center, the interface description document is periodically retrieved for service instance information from both static configuration and manual registration sources. The MD5 algorithm is used to calculate the hash value of the interface description document and compare it with the hash value in the memory cache. Only when the hash values ​​are inconsistent, the corresponding document data in the memory cache and the external database are refreshed.

[0018] S5: Client-side data display and interface retrieval; The frontend calls the aggregated document interface provided by the backend to obtain a unified intermediate data model list, extracts information such as the interface list, service name, source identifier, and specification version, and displays it on the service list page of the version-aware frontend display module; it displays the corresponding access path, request method, request parameters, and other information, and marks the service source and specification version to which the interface belongs; it also supports cross-service search for all services.

[0019] This method can proactively detect and identify Swagger 2.0 and OpenAPI 3.0 specifications, completing a unified conversion of heterogeneous document formats without manual configuration, thus avoiding document display errors. It can clearly mark the service source and specification version, facilitating rapid location of collection anomalies and significantly improving the efficiency of operation and maintenance troubleshooting. It adopts an event listening and hash comparison mechanism to achieve incremental updates, triggering refresh only when the document content changes, reducing invalid requests and lowering system resource consumption. At the same time, it supports multiple deployment methods such as pure registry center, pure static configuration, and hybrid mode, adapting to the entire scenario transition of enterprises from traditional architecture to cloud-native, making it more universal.

[0020] The present invention has been described in the above-described embodiments; however, these embodiments are merely examples for implementing the present invention. It must be noted that the disclosed embodiments do not limit the scope of the present invention. Conversely, any modifications and refinements made without departing from the spirit and scope of the present invention are within the scope of patent protection of the present invention.

Claims

1. A compatible aggregation method for API documents of multi-source heterogeneous microservices, characterized in that: Includes the following steps: S1: Perform service collection operations in parallel to obtain service instance information; The open platform portal is launched, and the multi-channel service discovery module performs service collection operations in parallel, simultaneously obtaining service instance information from multiple heterogeneous sources; and the service instance information is labeled with the corresponding source identifier. S2: Interface description document version detection and specification identification; The specification detection and version identification module sequentially traverses each service instance information in the service instance information list, and concatenates the service address and port number in each service instance information to obtain the service access address; Initiate a request based on the service access address, return the interface description document, and identify the specification version of the interface description document; S3: Unified conversion of heterogeneous interface documents; The heterogeneous document conversion engine, based on the specification version identified in step S2, calls the document conversion adapter corresponding to the specification version; extracts document data and encapsulates it. S4: Aggregated storage and caching; The aggregation storage and caching module synchronously saves the encapsulated unified intermediate data model to the memory cache, constructs key-value pairs with the service name as the key and the document data as the value, establishes a cache mapping, and sets the cache expiration time. S5: Client-side data display and interface retrieval; The frontend calls the aggregated document interface provided by the backend to obtain a unified intermediate data model list, extracts the interface list, service name, source identifier, and specification version, and displays it on the service list page of the version-aware frontend display module; it displays the corresponding access path, request method, and request parameter information, and marks the service source and specification version to which the interface belongs; it also supports cross-service search for all services.

2. The method for compatible aggregation of API documents for multi-source heterogeneous microservices as described in claim 1, characterized in that: In step S1, the service collection operation includes pulling the Eureka registry service, pulling the Nacos registry service, parsing the static configuration file service, and obtaining the manual registration service; Each service instance information includes the service name, service address, and port number; All service instance information from the multi-channel discovery module is aggregated, and the service instance information is compared using the service name + service address as the unique key value. Service instance information with duplicate key values ​​is removed, and the retained service instance information is saved to a list to form a service instance information list.

3. The compatible aggregation method for multi-source heterogeneous microservice API documents as described in claim 1, characterized in that: The specific details of step S2 are as follows: An HTTP request is sent to the OpenAPI 3.0 interface corresponding to the service access address after concatenation. If the response status code is 200, the interface description document returned by the OpenAPI 3.0 interface is parsed. If the interface description document contains the openapi field and starts with "3.", it is identified as the OpenAPI 3.0 specification version and the interface description document is stored. If the response status code is not 200, proceed with the following probe directly; If the response status code is 200, and the `openapi` field does not exist in the API description document or does not begin with "3.", then the following probes are performed: An HTTP request is sent to the Swagger 2.0 interface corresponding to the concatenated service access address. If the response status code is 200, the interface description document returned by the Swagger 2.0 interface is parsed. If the interface description document contains a swagger field and starts with "2.", it is identified as a Swagger 2.0 specification version and the interface description document is stored. If the response status code is not 200, or the interface description document does not contain a swagger field or the swagger field does not start with "2.", the service instance information is marked as having an abnormal interface description document.

4. The compatible aggregation method for multi-source heterogeneous microservice API documents as described in claim 1, characterized in that: The specific details of step S3 are as follows: The document conversion adapter parses the interface description document corresponding to each service instance information and extracts the document data. The document data includes the service name, source identifier, specification version, interface list, and interface entity data structure. The interface list includes the access path, request method, and request parameters. Each service instance information is encapsulated into a unified intermediate data model. After all services are encapsulated, a unified intermediate data model list is formed.

5. The method for compatible aggregation of API documents for multi-source heterogeneous microservices as described in claim 1, characterized in that: In step S4, the document data is simultaneously saved to an external database, and an index is built based on the source identifier and access path; For service instance information changes from the registry center, the interface description document is periodically retrieved for service instance information from both static configuration and manual registration sources. The MD5 algorithm is used to calculate the hash value of the interface description document and compare it with the hash value in the memory cache. Only when the hash values ​​are inconsistent, the corresponding document data in the memory cache and the external database are refreshed.

6. A compatible aggregation system for multi-source heterogeneous microservice API documents for implementing the method of any one of claims 1-5, characterized in that: The system includes a multi-channel service discovery module, a specification detection and version identification module, a heterogeneous document conversion engine, an aggregation storage and caching module, and a version-aware front-end display module; The multi-channel service discovery module is used to collect service instance information from multiple heterogeneous sources in parallel and label the source identifiers; The specification detection and version identification module is used to traverse service instance information and detect interface documents to identify OpenAPI 3.0 and Swagger 2.0 specification versions; The heterogeneous document conversion engine matches the corresponding document conversion adapter according to the recognition result, extracts the information of the interface description document, and uniformly encapsulates it into a preset intermediate data model. The aggregation storage and caching module is used to cache a unified intermediate data model, establish indexes, and implement incremental updates. The version-aware front-end display module is used to display service and interface information, indicate the source and specification version, and support cross-service search.

Images