Application programming interface document management method and device

Abstract

The present application relates to the field of Internet technology, and discloses an application programming interface document management method and device. The method includes: configuring a document generation tool and a document parsing tool in a private cloud management platform; annotating key information in the target interface code based on the annotation specification provided by the document generation tool; the key information includes: classification information of modules and components in the private cloud management platform; deploying the annotated target interface code through a pre-configured target pipeline, and using the document generation tool to generate the corresponding target interface document based on the key information; parsing the target interface document through the document parsing tool and displaying it in an HTML page; when displaying the target interface document, the document parsing tool provides a function of filtering and viewing based on key information. This method can automatically generate and maintain the API interface document of the private cloud management platform, and can filter and view it according to the classification information, thereby improving the platform's ease of use.

Description

Technical Field

[0001] The present application relates to the field of Internet technology, and in particular to an application programming interface document management method and device. Background Art

[0002] The private cloud management platform is a key tool on the private cloud. It targets the needs of unified monitoring and automated operation and maintenance of the industry private cloud data center, and realizes the integrated monitoring and visualization of the cloud infrastructure, PaaS (Platform as a Service), business application systems and non-cloud devices of the industry private cloud data center, so that organizations can create and manage their own cloud infrastructure to meet specific performance requirements. In order to ensure that users can effectively use the API (Application Programming Interface) provided by the platform, developers need to create detailed API interface documents for users to refer to and consult.

[0003] The traditional way of writing API interface documents usually relies on developers to write them manually, which takes a lot of time and is prone to errors and omissions. This method is gradually being eliminated. In related technologies, document automatic generation tools are also used to automatically create interface documents. However, current automatic generation tools only provide limited document generation functions and cannot meet the complex requirements of private cloud management platforms. Private cloud management platforms are composed of multiple modules and components. The API documents generated by current automatic generation tools are relatively scattered, making them difficult to manage and view, making it difficult for users to quickly find the information they need. At the same time, in the process of iterative updates of platform versions, how to ensure the correctness and timeliness of interface documents also poses a considerable challenge to developers.

[0004] Based on this, it is necessary to find a method to optimize the generation and management process of the API interface document of the private cloud management platform to improve the availability and maintainability of the private cloud management platform. Summary of the invention

[0005] In view of this, the present application aims to propose an application programming interface document management method and device to realize the automatic generation and timely maintenance of platform application programming interface documents, and to realize the classified viewing of each module and component information in the platform to improve the user experience.

[0006] To achieve the above purpose, the technical solution of this application is as follows:

[0007] A first aspect of an embodiment of the present application provides an application programming interface document management method, which is applied to a private cloud management platform and includes:

[0008] Configure document generation tools and document parsing tools in the private cloud management platform;

[0009] Based on the annotation specification provided by the document generation tool, key information in the target interface code is annotated; the key information includes: classification information of modules and components in the private cloud management platform;

[0010] Deploy the annotated target interface code through a pre-configured target pipeline, and use the document generation tool to generate a corresponding target interface document based on the key information;

[0011] The target interface document is parsed by the document parsing tool and displayed in an HTML page; when displaying the target interface document, the document parsing tool provides a function of filtering and viewing based on the key information.

[0012] Optionally, based on the annotation specification provided by the document generation tool, key information in the target interface code is annotated, including:

[0013] Use the decoration structure to package the return data of the interface in the target interface code to generate a JSON structure;

[0014] The return data is annotated based on the annotation format provided by the document generation tool, and the name, function, description, parameters, request of the target interface code and the classification information of each module and component in the private cloud management platform are annotated; wherein the classification information is annotated based on the custom annotation format provided by the document generation tool.

[0015] Optionally, before marking the classification information of the target interface code, the method further includes:

[0016] Using the extended syntax provided by the document parsing tool, define all optional classification items in the target interface code;

[0017] The classification information of the target interface code is specifically marked as follows:

[0018] Based on the custom annotation format provided by the document generation tool, select at least one item from all optional classification items for annotation.

[0019] Optionally, the target interface code that has been marked is deployed through a pre-configured target pipeline, and the document generation tool is used to generate a corresponding target interface document based on the key information, including:

[0020] Push the annotated target interface code to the code repository and store it in a specified directory as the latest version of the interface code;

[0021] Triggering the target pipeline to start code deployment of the target interface code; the code deployment includes the following operations: pulling code, building an image container, testing code, and deploying to a production environment;

[0022] After pulling the code, the document generation tool is called to extract the key information marked in the target interface code, and the target interface document is generated based on the key information.

[0023] Optionally, parsing the target interface document by the document parsing tool and displaying it in an HTML page includes:

[0024] After building the image container, open the corresponding HTML page through the address provided by the document parsing tool;

[0025] The script of the document parsing tool is loaded to parse and display the target interface document.

[0026] Optionally, the annotated target interface code is pushed to a code repository and stored in a specified directory as the latest version of the interface code, including:

[0027] In the case where the target interface code does not carry a version number, using the target interface code to overwrite the file with the same name in the specified directory;

[0028] In the case where the target interface code carries a version number, the file with the same name in the designated directory is retained when the target interface code is stored.

[0029] Optionally, the application programming interface document management method further includes:

[0030] A historical version query interface is configured in the private cloud management platform; based on the interface name obtained by the historical version query interface, the version information of all interface documents corresponding to the interface name is queried in the specified directory and displayed;

[0031] A document query interface is configured in the private cloud management platform; based on the interface name and version number obtained by the document query interface, a corresponding interface document is obtained in the specified directory, and the document parsing tool is used to parse and display the document;

[0032] A document comparison interface is configured in the private cloud management platform; based on two different version information obtained by the document comparison interface, two corresponding interface documents are obtained; the differences between the two interface documents are compared, and a difference report is generated and displayed based on the differences.

[0033] Optionally, based on two different version information obtained by the document comparison interface, two corresponding interface documents are obtained; and the difference between the two interface documents is compared, and a difference report is generated and displayed based on the difference, including:

[0034] Based on the two versions of information, obtain the corresponding two versions of interface documents from the specified directory;

[0035] Use the Swagger parser to obtain element information of the two versions of the interface documents; the element information includes: mapping information, parameter information, attribute information, node information and class information;

[0036] Compare the element information of the two versions of the interface documents, determine the element information updated by the newer version of the interface document relative to the old version, and generate and display a difference report;

[0037] The difference report is displayed on an HTML page through an HTML renderer.

[0038] Optionally, after obtaining the interface name and version number based on the document query interface and obtaining the corresponding interface document in the specified directory, the method further includes:

[0039] The document query interface is called by a third-party document system to obtain and parse the interface document, and the interface document is displayed in an interactive interface of the third-party document system.

[0040] According to a second aspect of an embodiment of the present application, an application programming interface document management device is provided, which is used to implement the steps in the method provided in the first aspect of the embodiment of the present application, and the device includes:

[0041] An installation module is configured to configure a document generation tool and a document parsing tool in a private cloud management platform;

[0042] A marking module is configured to mark key information in the target interface code based on the annotation specification provided by the document generation tool; the key information includes: classification information of modules and components in the private cloud management platform;

[0043] A deployment module is configured to deploy the target interface code marked by a pre-configured target pipeline, and use the document generation tool to generate a corresponding target interface document based on the key information;

[0044] The document viewing module is configured to parse the target interface document through the document parsing tool and display it in an HTML page; when displaying the target interface document, the document parsing tool provides a function of filtering and viewing based on the key information.

[0045] The application programming interface document management method provided in this application is adopted, and a document generation tool and a document parsing tool for automatically generating API interface documents are pre-deployed in the private cloud management platform. Before the target interface code is deployed, the key information in the interface code is annotated based on the annotation specification provided by the document generation tool, wherein the key information includes the classification information of each module and component in the private cloud management platform. When the platform code is iteratively updated, the interface code is deployed through the pipeline, and the key information annotated in the code is automatically identified and extracted by the document generation tool during the code deployment process, and then the corresponding target interface document is generated based on the key information. In this application, the generated target interface document is parsed by a document parsing tool, and an HTML page is provided for the user to view. The classification information in the target interface document is identified and parsed by the document parsing tool, so that the classification information of each module and component is displayed in the HTML page, which is convenient for users to filter and find the required document information through the classification information.

[0046] The application programming interface document management method provided by the present application annotates the key information of the code in the interface code according to the annotation specifications of the document generation tool, so that the corresponding target interface document is automatically generated using the document generation tool in the subsequent update process of the interface version, so that the platform interface code and the interface document are updated synchronously, without the need for manual maintenance and updating of the interface document, thereby avoiding data errors that may be caused by manual maintenance and saving maintenance costs. In addition, the target interface document is parsed by a document parsing tool and displayed according to classified information, so that users can filter and view according to the classified information and quickly find the required document information. In summary, the method provided by the present application can improve the timeliness and ease of use of the private cloud management platform and enhance the user experience. BRIEF DESCRIPTION OF THE DRAWINGS

[0047] In order to more clearly illustrate the technical solutions of the embodiments of the present application, the drawings required for use in the description of the embodiments of the present application will be briefly introduced below. Obviously, the drawings described below are only some embodiments of the present application. For ordinary technicians in this field, other drawings can be obtained based on these drawings without paying any creative labor.

[0048] Figure 1 is a flow chart of an application programming interface document management method proposed in one embodiment of the present application;

[0049] Figure 2 This is a flowchart of the private cloud platform API interface version update in one embodiment of the present application;

[0050] Figure 3 This is a working principle diagram of document comparison in one embodiment of the present application;

[0051] Figure 4 It is a schematic diagram of an application programming interface document management device proposed in one embodiment of the present application. DETAILED DESCRIPTION

[0052] The following will be combined with the drawings in the embodiments of the present application to clearly and completely describe the technical solutions in the embodiments of the present application. Obviously, the described embodiments are part of the embodiments of the present application, not all of the embodiments. Based on the embodiments in the present application, all other embodiments obtained by ordinary technicians in this field without creative work are within the scope of protection of this application.

[0053] It should be understood that the references to "one embodiment" or "an embodiment" throughout the specification mean that the specific features, structures, or characteristics associated with the embodiment are included in at least one embodiment of the present application. Therefore, the references to "in one embodiment" or "in an embodiment" appearing throughout the specification do not necessarily refer to the same embodiment. In addition, these specific features, structures, or characteristics may be combined in any suitable manner in one or more embodiments.

[0054] In the various embodiments of the present application, it should be understood that the size of the serial numbers of the following processes does not mean the order of execution. The execution order of each process should be determined by its function and internal logic, and should not constitute any limitation on the implementation process of the embodiments of the present application.

[0055] Exemplary embodiments will be described in detail herein, examples of which are shown in the accompanying drawings. When the following description refers to the drawings, unless otherwise indicated, the same numbers in different drawings represent the same or similar elements. The embodiments described in the following exemplary embodiments do not represent all embodiments consistent with the present application. Instead, they are merely examples of devices and methods consistent with some aspects as detailed in the present application.

[0056] It should be noted that, in the absence of conflict, the embodiments and features in the embodiments of the present application may be combined with each other.

[0057] Private cloud has become the preferred environment for many organizations to deploy and manage enterprise applications. A private cloud is built for individual use by users, owns the infrastructure, and can control how applications are deployed on this infrastructure. In a private cloud, services and infrastructure are always maintained on a private network, and the hardware and software are dedicated to the organization, making it easier for the organization to customize resources to meet specific needs.

[0058] The private cloud management platform provided by current private cloud providers for users to deploy private cloud environments cannot fully meet some of the users' operation and maintenance and monitoring requirements for private cloud infrastructure, PaaS platform, and business application systems. Therefore, customers also need to call the corresponding API interface of the private cloud management platform to achieve personalized operation and maintenance and monitoring requirements. The private cloud management platform is composed of multiple modules and components. The platform developers need to create detailed API interface documents for different modules and components for users to refer to. Traditional API interface documents are manually written and managed, which is very time-consuming to maintain. It is easy to have document information errors, omissions, and failure to update in time. The accuracy and timeliness of API interface documents cannot be guaranteed, which may cause users to be unable to call API interfaces normally. In the related art, document generation tools are used to generate API documents. The functions of such document generation tools (such as Swagger tools) are relatively limited and cannot meet the requirements of complex private cloud management platforms, such as API grouping. In addition, since the private cloud management platform includes multiple modules and components, the generated API interface documents are also scattered in various parts, making it difficult for users to quickly find the required information.

[0059] Based on this, the present application provides an application programming interface document management method, which can automatically create and timely maintain the API interface document of the private cloud management platform, and enable users to classify and view the document information of each module and component, quickly find the required content, and improve the user experience.

[0060] The present application will be described in detail below with reference to the accompanying drawings and in combination with embodiments.

[0061] Figure 1 1 is a flow chart of an application programming interface document management method proposed in an embodiment of the present application. Figure 1 As shown, the method includes:

[0062] S1: Configure document generation tools and document parsing tools in the private cloud management platform;

[0063] S2: Based on the annotation specification provided by the document generation tool, annotate key information in the target interface code; the key information includes: classification information of modules and components in the private cloud management platform;

[0064] S3: deploying the annotated target interface code through a pre-configured target pipeline, and using the document generation tool to generate a corresponding target interface document based on the key information;

[0065] S4: the target interface document is parsed by the document parsing tool and displayed in an HTML page; when displaying the target interface document, the document parsing tool provides a function of filtering and viewing based on the key information.

[0066] In this embodiment, the document generation tool and the document parsing tool are first integrated into the private cloud management platform. The document generation tool is used to automatically create API interface documents. In actual applications, an adapted document generation tool can be selected according to needs. Swagger is an open source toolset for defining, building, documenting and testing RESTful APIs. In this embodiment, the Swagger tool (Go-Swagger) is selected as a document generation tool to automatically create API interface documents. ReDoc is an API document generation tool based on the OpenAPI (Open Application Programming Interface) specification. In this embodiment, the ReDoc tool is used as a document parsing tool to parse the API interface document generated by the Swagger tool and display it through an HTML page.

[0067] Based on the annotation specifications provided by the document generation tool, the key information in the target interface code to be delivered by the private cloud management platform is annotated. Given that the private cloud involves multiple modules (such as computing modules, storage modules, network modules, user modules, etc.), when annotating key information, the corresponding classification information is added to some codes of each module and component during the annotation stage to enable subsequent filtering and viewing of interface documents according to classification.

[0068] In addition, in this embodiment, a target pipeline is pre-configured for automatic version update and document generation of the platform API. That is, the CI / CD (Continuous Integration / Continuous Delivery) pipeline. After the target interface code is annotated, it is automatically deployed and released through the pre-configured target pipeline. During the deployment of the target pipeline, the document generation tool is used to identify and extract the annotated key information, and the target interface document of the corresponding format is automatically generated based on the key information.

[0069] The Swagger tool itself does not have the function of identifying classification information, but it provides a custom annotation format, while the ReDoc tool can identify and display custom classification information. Based on this, in this embodiment, the classification information is added to the target interface code as a custom annotation, and extracted through the Swagger tool so that the interface document is subsequently opened through the HTML page provided by the ReDoc tool. The ReDoc tool parses the target interface document, reads the key information therein and displays it on the page, and provides the function of searching and filtering based on the key information. Specifically, users can filter and view the API interface documents based on the classification information; they can also use ReDoc's custom search function to search and filter the content in the API interface document based on key information such as keywords and functions, so as to quickly find the required information. For example: if a user needs to create a virtual machine, he can search for the keyword "virtual machine".

[0070] In this embodiment, by using a document generation tool in the target pipeline, the key information of the target interface code is automatically extracted and a detailed, consistent and timely target interface document is generated, thereby optimizing the generation and maintenance of the API interface document and improving the accuracy and timeliness of the document. The target interface document is parsed by a document parsing tool, and the document parsing tool is used to implement keyword search and classification screening and viewing of the interface document, which facilitates users to quickly find the information they need and improves the user experience. In addition, the document generation tool and the document parsing tool are integrated into the private cloud management platform, eliminating the need to deploy a separate dedicated document management system, reducing the deployment difficulty and complexity of the private cloud management platform, and reducing the maintenance difficulty of the private cloud management platform.

[0071] As an implementation mode of the present application, based on the annotation specification provided by the document generation tool, key information in the target interface code is annotated, including:

[0072] Use the decoration structure to package the return data of the interface in the target interface code to generate a JSON structure;

[0073] The return data is annotated based on the annotation format provided by the document generation tool, and the name, function, description, parameters, request of the target interface code and the classification information of each module and component in the private cloud management platform are annotated; wherein the classification information is annotated based on the custom annotation format provided by the document generation tool.

[0074] In one embodiment, the key information in the target interface code is annotated based on the annotation specification provided by the document generation tool. Specifically, the return data of the interface is packaged using a decorative structure and customized into a json structure to be output externally. The return data is annotated according to the annotations provided by Swagger, and the key information such as the name, function, description parameters, request, calling method, return value and classification information in the target interface code is annotated.

[0075] The following examples illustrate how key information is marked. As shown in the figure below, lines 01-07 are all marked to illustrate information such as routing, request methods, interfaces, etc. Among them, line 01 includes the route "route", the routing method is "GET", the path is " / example / of / route", the interface name is "demoRequest", and the classification information is "Classification 1". Line 02 is the function description "Annotation Sample", lines 06-26 are the structure (DemoResponseWrapper) of the returned data (parameters), and lines 28-32 are input parameters. In this embodiment, before the target interface code is deployed, the key information in the target interface code is marked based on the annotation specification provided by Swagger, thereby realizing the automatic generation of the target interface document.

[0076]

[0077] The native Swagger-UI does not support the API grouping display function. Users cannot view the classification information of the interface document through the Swagger tool. It is very time-consuming to find the required content, resulting in low document availability and poor user experience. In order to improve the availability of the document, the target interface document is parsed by the ReDoc tool in this embodiment, and the extended syntax of the ReDoc tool is used to support the classification and tagging of the interface document. In addition, users can also search and filter the document content according to keywords, functions and other information, so that they can quickly find the required information.

[0078] As an implementation manner of the present application, before marking the classification information of the target interface code, it also includes:

[0079] Using the extended syntax provided by the document parsing tool, define all optional classification items in the target interface code;

[0080] The classification information of the target interface code is specifically marked as follows:

[0081] Based on the custom annotation format provided by the document generation tool, select at least one item from all optional classification items for annotation.

[0082] In one embodiment, before adding classification information to the target interface code, first use the extended syntax provided by the ReDoc tool to define all classification items that may be involved in all modules and components in the private cloud platform. Then, select at least one classification item from all the defined classification items for annotation. A target interface document can add multiple classification items of different dimensions. As shown in the figure below, through the extended syntax provided by the ReDoc tool, use x-tagGroups to list all optional classification items of the target interface code, and then the target interface document can be classified by specifying the classification to which it belongs. The figure below lists two major categories of classification items, namely API Group, which includes 3 classification items, and Version Group, which includes 3 classification items. When annotating classification information for the target interface code, you can select multiple classification items of different dimensions for annotation, such as annotating "Classification 1" and "v2".

[0083]

[0084] As an implementation mode of the present application, the target interface code marked by the pre-configured target pipeline deployment is used, and the document generation tool is used to generate the corresponding target interface document based on the key information, including:

[0085] Push the annotated target interface code to the code repository and store it in a specified directory as the latest version of the interface code;

[0086] Triggering the target pipeline to start code deployment of the target interface code; the code deployment includes the following operations: pulling code, building an image container, testing code, and deploying to a production environment;

[0087] After pulling the code, the document generation tool is called to extract the key information marked in the target interface code, and the target interface document is generated based on the key information.

[0088] In one embodiment, after the target interface code is marked, it is pushed to the CI / CD pipeline for deployment. During the deployment process, a document generation tool is used to generate a corresponding target interface document based on the key information of the target interface document.

[0089] Figure 2 This is a flowchart of the private cloud platform API interface version update in one embodiment of the present application. Figure 2 As shown, the specific steps of code deployment in this embodiment are as follows:

[0090] (1) When the version is updated, the target interface code is pushed to a code repository with version management function (such as github, gitlab, etc.), and the code is stored in the specified directory as the latest version of the code file, triggering the target pipeline CI / CD to start the deployment process of the target interface code;

[0091] (2) The code repository triggers the build process, downloads the code, and then performs compilation, unit testing, static analysis, security analysis, and other operations in sequence. It calls the document generation tool provided by Go-Swagger, extracts the key information annotated in the target interface code according to the Swagger annotation, including functions, parameters, calling methods, and return values, and automatically generates detailed, consistent, and timely API documentation (target interface documentation). Build a container image, and then push the image to the container registry for storage (development environment);

[0092] (3) Then the image test process is triggered, which goes through three stages, including: development stage, quality inspection stage and pre-release stage. The development stage includes: downloading the image and deploying it to the development environment; the quality inspection stage includes: downloading the image, deploying it to the quality inspection environment and integration testing.

[0093] A series of comprehensive tests will be conducted at this stage, some of which may require manual confirmation by the tester to see if they have passed. During the testing phase, users can use the ReDoc tool to view the target interface document. Specifically, by accessing the web address provided by the ReDoc tool, the target interface document is loaded and displayed in the HTML web page. After the test is completed, pre-release operations are performed: download the image and deploy it to the pre-release environment, and run the load test. After the test passes, push the image to the container registry for storage (pre-release environment);

[0094] (4) Finally, the deployment phase is triggered, the image is downloaded from the container registry, and then deployed to the production environment to complete the API interface version update operation.

[0095] As an implementation mode of the present application, the target interface document is parsed by the document parsing tool and displayed in an HTML page, including:

[0096] After building the image container, open the corresponding HTML page through the address provided by the document parsing tool;

[0097] The script of the document parsing tool is loaded to parse and display the target interface document.

[0098] In one embodiment, when a user needs to view the target interface document, the user opens the corresponding HTML page by entering the address provided by the ReDoc tool, loads the target interface document into the page, parses the target interface document through the script of the ReDoc tool, identifies key information marked in the target interface document, including classification information, keywords, functions, etc., and displays the classification information on the web page, providing users with the function of searching and filtering according to the classification information, keywords, and functions of modules and components, thereby improving the usability of the document.

[0099] As an implementation method of the present application, the annotated target interface code is pushed to the code repository and stored in a designated directory as the latest version of the interface code, including:

[0100] In the case where the target interface code does not carry a version number, using the target interface code to overwrite the file with the same name in the specified directory;

[0101] In the case where the target interface code carries a version number, the file with the same name in the designated directory is retained when the target interface code is stored.

[0102] In one embodiment, the version number in the document file name is used as the basis for document historical version management. All automatically generated interface documents are uniformly stored in a designated directory and carried together during packaging and deployment, so that the documents are provided as the private cloud management platform is deployed.

[0103] Specifically, the document generation tool generates a target interface document with the corresponding name according to the version number carried in the target interface code. After each code submission triggers the CI / CD pipeline, the Swagger tool will generate a latest interface document accordingly. If the target interface code does not carry a version number, the name of the target interface document generated each time is the same (for example, the file name is api-latest.yml), and when it is stored in the specified directory, it will overwrite the interface document in the directory.

[0104] If the target interface code carries a version number, the Swagger tool will include the version number in the document name when generating the interface document (for example, the file name is api-v1.0.0.yml), which means that the old version of the interface document in the specified directory will not be overwritten. In addition, the ReDoc tool will also identify the version number when parsing the target interface document, and automatically append the corresponding version information in a fixed position by using placeholder replacement, which is convenient for users to view.

[0105] As an implementation of the present application, the application programming interface document management method further includes:

[0106] A historical version query interface is configured in the private cloud management platform; based on the interface name obtained by the historical version query interface, the version information of all interface documents corresponding to the interface name is queried in the specified directory and displayed;

[0107] A document query interface is configured in the private cloud management platform; based on the interface name and version number obtained by the document query interface, a corresponding interface document is obtained in the specified directory, and the document parsing tool is used to parse and display the document;

[0108] A document comparison interface is configured in the private cloud management platform; based on two different version information obtained by the document comparison interface, two corresponding interface documents are obtained; the differences between the two interface documents are compared, and a difference report is generated and displayed based on the differences.

[0109] In one embodiment, interfaces for document search, version viewing, and comparison functions are also integrated into the private cloud management platform, eliminating the need to deploy additional dependent components or third-party document systems, thereby further improving the convenience of API document management on the private cloud management platform and the platform's ease of use.

[0110] Specifically, a historical version query interface is integrated in the private cloud management platform to query all historical document version information of the platform. According to the interface name information passed in, the version information of all interface documents corresponding to the name is searched from the specified directory where the interface documents are stored and displayed in the HTML page. Optionally, according to the needs, a viewing link for each historical version of the interface document can be added to the result page returned by the historical version query interface. By clicking the link, the document query interface is called, and the historical version of the interface document can be viewed using the ReDoc tool.

[0111] A document query interface is integrated in the private cloud management platform. According to the passed interface name and version number, the corresponding interface document is returned. The interface directly returns an HTML page based on the ReDoc tool, which can provide a more beautiful and more functional document display interface than Swagger-UI, including filtering and viewing by classified information, searching by keywords and functions, etc.

[0112] The document comparison interface is integrated in the private cloud management platform. According to the two different version information passed in, the corresponding interface documents are obtained from the specified directory and compared, a difference report is generated, and an HTML page of the comparison results is returned. Through this interface, the version comparison of the interface document can be performed locally on the user without the need to deploy or rely on a third-party system, which facilitates the maintenance and management of the interface document and prevents data leakage.

[0113] Compared with the need to deploy additional dependent components or third-party document systems to provide document query, classification, search, version management and version comparison, this method supports integrating all these functions into the private cloud management platform service, making the platform more flexible in deployment and less resource intensive.

[0114] As an implementation mode of the present application, based on two different version information obtained by the document comparison interface, two corresponding interface documents are obtained; the difference between the two interface documents is compared, and a difference report is generated and displayed based on the difference, including:

[0115] Based on the two versions of information, obtain the corresponding two versions of interface documents from the specified directory;

[0116] Use the Swagger parser to obtain element information of the two versions of the interface documents; the element information includes: mapping information, parameter information, attribute information, node information and class information;

[0117] Compare the element information of the two versions of the interface documents, determine the element information updated by the newer version of the interface document relative to the old version, and generate and display a difference report;

[0118] The difference report is displayed on an HTML page through an HTML renderer.

[0119] In one embodiment, the document comparison interface is used to read the interface documents corresponding to the two version information (e.g., api-v1.0.0.yml file and api-v2.0.0.yml file) in the specified directory according to the two different version information passed in. All elements in the interface document, including Map, Parameter, Property, Endpoint, and Model, are obtained through the swagger parser, and then these elements are compared to obtain the elements that are added, deleted, and modified in the newer interface document relative to the older interface document. A difference report is generated based on the difference, and an HTML page is returned through the interface for display.

[0120] In this embodiment, the specific steps of document comparison are as follows:

[0121] (1) After obtaining the two versions of the interface documents from the specified directory, parse the documents through the Swagger parser and convert them into internal data structures. The interface documents generated by the Swagger tool can be in YAML format or JSON format, and the Swagger parser parses the documents into objects or data structures;

[0122] (2) Compare the API paths of the interface documents: Once both documents are successfully parsed, the Swagger parser will compare the API paths of the documents, check the path definitions in the two documents and determine the differences between them. Possible differences include: adding new paths, deleting paths, and changes in parameters, request bodies, responses, etc. in the paths;

[0123] Compare parameters and responses: Compare the parameters and responses in the API path, check the name, type, required and other attributes of the parameters, as well as the differences in the status code, content type, mode and other aspects of the response, and record them;

[0124] Compare descriptions and comments: The Swagger parser also compares the descriptions and comments in the interface document, checks the description information of elements such as API paths, parameters, responses, and determines the differences between the two versions. Possible differences include: modification, addition, or deletion of descriptions;

[0125] (3) After the interface document comparison is completed, the Swagger parser generates a difference report based on the comparison results. The difference report lists the changes in the newer version of the interface document relative to the older version of the interface document, including changes in API paths, parameters, descriptions, and other information. The difference report is generated through the HTML Render renderer to display the web page content, and the document comparison interface returns an HTML page to display the final comparison results.

[0126] Figure 3 1 is a working principle diagram of document comparison in one embodiment of the present application. Figure 3 As shown in the figure, two different versions of the interface documents Swagger YAML1 and Swagger YAML2 are parsed by the Swagger parser, and all elements (including map, Parameter, Property, Endpoint, Model) are obtained for comparison to obtain the comparison results (such as Figure 3 The SwaggerDiff data structure shown in the figure records the information of newly added, deleted or modified nodes, and further generates web page display content through the HTML renderer (HTML Render) for display in the HTML page.

[0127] Compared with relying on an external third-party document system, this embodiment encapsulates the complex version comparison function into an interface of the management platform, relies on the CI / CD pipeline to automatically iterate the document and release it with the service, so as to obtain the comparison content directly on the machine where the service is located. In addition, the comparison results are stored on the machine where the service is located, so as to obtain the comparison results more efficiently.

[0128] As an implementation mode of the present application, after obtaining the interface name and version number based on the document query interface and obtaining the corresponding interface document in the specified directory, it also includes:

[0129] The document query interface is called by a third-party document system to obtain and parse the interface document, and the interface document is displayed in an interactive interface of the third-party document system.

[0130] In one embodiment, the private cloud management platform also provides the ability to access third-party document systems, such as the YApi system, to implement the parsing and display of target interface documents. Specifically, the YApi system calls the document query interface of the private cloud management platform, obtains the corresponding interface document from the specified directory based on the API interface name and version number, and parses it in the YApi system, and displays it through the third-party interactive interface of YApi. By providing access to third-party document systems, the flexibility of the private cloud management platform is improved, and at the same time, there is no need to integrate parsing tools (such as ReDoc tools) into the platform, reducing resource usage.

[0131] Based on the same inventive concept, an embodiment of the present application provides an application programming interface document management device. Figure 4 , Figure 4 FIG. 1 is a schematic diagram of an application programming interface document management device 100 proposed in an embodiment of the present application. Figure 4 As shown, the device comprises:

[0132] An installation module 101 is configured to configure a document generation tool and a document parsing tool in a private cloud management platform;

[0133] The annotation module 102 is configured to annotate key information in the target interface code based on the annotation specification provided by the document generation tool; the key information includes: classification information of modules and components in the private cloud management platform;

[0134] A deployment module 103 is configured to deploy the target interface code marked by a pre-configured target pipeline, and use the document generation tool to generate a corresponding target interface document based on the key information;

[0135] The document viewing module 104 is configured to parse the target interface document through the document parsing tool and display it in an HTML page; when displaying the target interface document, the document parsing tool provides a function of filtering and viewing based on the key information.

[0136] As an implementation manner of the present application, the annotation module 102 is configured to annotate key information in the target interface code based on the annotation specification provided by the document generation tool, specifically including:

[0137] Use the decoration structure to package the return data of the interface in the target interface code to generate a JSON structure;

[0138] The return data is annotated based on the annotation format provided by the document generation tool, and the name, function, description, parameters, request of the target interface code and the classification information of each module and component in the private cloud management platform are annotated; wherein the classification information is annotated based on the custom annotation format provided by the document generation tool.

[0139] As an implementation mode of the present application, before marking the classification information of the target interface code, the marking module 102 is further configured to define all optional classification items in the target interface code using an extended syntax provided by a document parsing tool;

[0140] The marking module 102 is configured to mark the classification information of the target interface code, specifically including:

[0141] Based on the custom annotation format provided by the document generation tool, select at least one item from all optional classification items for annotation.

[0142] As an implementation mode of the present application, the deployment module 103 is configured to deploy the target interface code marked by the pre-configured target pipeline, and use the document generation tool to generate the corresponding target interface document based on the key information, specifically including:

[0143] Push the annotated target interface code to the code repository and store it in a specified directory as the latest version of the interface code;

[0144] Triggering the target pipeline to start code deployment of the target interface code; the code deployment includes the following operations: pulling code, building an image container, testing code, and deploying to a production environment;

[0145] After pulling the code, the document generation tool is called to extract the key information marked in the target interface code, and the target interface document is generated based on the key information.

[0146] As an implementation manner of the present application, the document viewing module 104 is configured to parse the target interface document through the document parsing tool and display it in an HTML page, specifically including:

[0147] After building the image container, open the corresponding HTML page through the address provided by the document parsing tool;

[0148] The script of the document parsing tool is loaded to parse and display the target interface document.

[0149] As an implementation manner of the present application, the deployment module 103 is configured to push the annotated target interface code to the code repository and store it in a specified directory as the latest version of the interface code, specifically including:

[0150] In the case where the target interface code does not carry a version number, using the target interface code to overwrite the file with the same name in the specified directory;

[0151] In the case where the target interface code carries a version number, the file with the same name in the designated directory is retained when the target interface code is stored.

[0152] As an implementation mode of the present application, the installation module 101 is further configured to configure a historical version query interface, a document query interface and a document comparison interface in the private cloud management platform;

[0153] The application programming interface document management device 100 further includes a query module for executing the following steps:

[0154] Based on the interface name obtained by the historical version query interface, query the version information of all interface documents corresponding to the interface name in the specified directory and display them;

[0155] Based on the interface name and version number obtained by the document query interface, obtain the corresponding interface document in the specified directory, and use the document parsing tool to parse and display it;

[0156] Based on the two different version information obtained by the document comparison interface, two corresponding interface documents are obtained; the differences between the two interface documents are compared, and a difference report is generated and displayed based on the differences.

[0157] As an implementation mode of the present application, the query module is configured to obtain two corresponding interface documents based on two different version information obtained by the document comparison interface; compare the differences between the two interface documents, generate and display a difference report based on the differences, including:

[0158] Based on the two versions of information, obtain the corresponding two versions of interface documents from the specified directory;

[0159] Use the Swagger parser to obtain element information of the two versions of the interface documents; the element information includes: mapping information, parameter information, attribute information, node information and class information;

[0160] Compare the element information of the two versions of the interface documents, determine the element information updated by the newer version of the interface document relative to the old version, and generate and display a difference report;

[0161] The difference report is displayed on an HTML page through an HTML renderer.

[0162] As an implementation manner of the present application, the query module is further configured to, after obtaining the corresponding interface document in the specified directory based on the interface name and version number obtained by the document query interface, perform the following steps:

[0163] The document query interface is called by a third-party document system to obtain and parse the interface document, and the interface document is displayed in an interactive interface of the third-party document system.

[0164] Based on the same inventive concept, an embodiment of the present application provides a computer program product. The computer program product includes a computer program, and when the computer program is executed by a processor, the steps in the application programming interface document management method described in any of the above embodiments of the present application are implemented.

[0165] Based on the same inventive concept, an embodiment of the present application provides a readable storage medium on which a computer program is stored. When the computer program is executed by a processor, the steps in the application programming interface document management method described in any of the above embodiments of the present application are implemented.

[0166] Based on the same inventive concept, an embodiment of the present application provides an electronic device. The electronic device includes a memory, a processor, and a computer program stored in the memory and executable on the processor, and when the computer program is executed by the processor, the steps in the application programming interface document management method described in any of the above embodiments of the present application are implemented.

[0167] Regarding the device in the above embodiment, the specific manner in which each module performs operations has been described in detail in the embodiment of the method, and will not be elaborated here.

[0168] The above description is only a preferred embodiment of the present application and is not intended to limit the present application. Any modifications, equivalent substitutions, improvements, etc. made within the spirit and principles of the present application should be included in the protection scope of the present application.

[0169] For the method embodiments, for the sake of simplicity, they are all described as a series of action combinations, but those skilled in the art should be aware that the present application is not limited by the order of the actions described, because according to the present application, some steps can be performed in other orders or simultaneously. Secondly, those skilled in the art should also be aware that the embodiments described in the specification are all preferred embodiments, and the actions and components involved are not necessarily required by the present application.

[0170] Those skilled in the art will appreciate that the embodiments of the present application may be provided as methods, devices, or computer program products. Therefore, the embodiments of the present application may adopt the form of a complete hardware embodiment, a complete software embodiment, or an embodiment in combination with software and hardware. Moreover, the embodiments of the present application may adopt the form of a computer program product implemented on one or more computer-usable storage media (including but not limited to disk storage, CD-ROM, optical storage, etc.) containing computer-usable program codes.

[0171] The embodiments of the present application are described with reference to the flowcharts and / or block diagrams of the methods, terminal devices (systems), and computer program products according to the embodiments of the present application. It should be understood that each process and / or box in the flowchart and / or block diagram, as well as the combination of the processes and / or boxes in the flowchart and / or block diagram, can be implemented by computer program instructions. These computer program instructions can be provided to a processor of a general-purpose computer, a special-purpose computer, an embedded processor, or other programmable data processing terminal device to generate a machine, so that the instructions executed by the processor of the computer or other programmable data processing terminal device generate instructions for implementing the processes in the flowchart and / or block diagram. Figure 1 A process or multiple processes and / or boxes Figure 1 A device that provides the functions specified in a block or multiple blocks.

[0172] These computer program instructions may also be stored in a computer-readable memory capable of directing a computer or other programmable data processing terminal device to operate in a specific manner, so that the instructions stored in the computer-readable memory produce a manufactured product including an instruction device, which implements the process Figure 1 A process or multiple processes and / or boxes Figure 1 A function specified in one or more boxes.

[0173] These computer program instructions can also be loaded onto a computer or other programmable data processing terminal device so that a series of operating steps are executed on the computer or other programmable terminal device to produce a computer-implemented process, thereby providing instructions for implementing the process in the computer or other programmable terminal device. Figure 1 A process or multiple processes and / or boxes Figure 1 The steps for the functions specified in one or more boxes.

[0174] Although the preferred embodiments of the present application have been described, those skilled in the art may make additional changes and modifications to these embodiments once they are aware of the basic creative concepts. Therefore, the present application is interpreted as including the preferred embodiments and all changes and modifications that fall within the scope of the embodiments of the present application.

[0175] Finally, it should be noted that, in this article, relational terms such as first and second, etc. are only used to distinguish one entity or operation from another entity or operation, and do not necessarily require or imply any such actual relationship or order between these entities or operations. Moreover, the terms "include", "comprise" or any other variants thereof are intended to cover non-exclusive inclusion, so that a process, method, article or terminal device including a series of elements includes not only those elements, but also other elements not explicitly listed, or also includes elements inherent to such process, method, article or terminal device. In the absence of further restrictions, the elements defined by the sentence "comprise a ..." do not exclude the existence of other identical elements in the process, method, article or terminal device including the elements.

[0176] The above is a detailed introduction to the application programming interface document management method and device provided by the present application. Specific examples are used in this article to illustrate the principles and implementation methods of the present application. The description of the above embodiments is only used to help understand the method of the present application and its core idea; at the same time, for general technical personnel in this field, according to the idea of ​​the present application, there will be changes in the specific implementation method and application scope. In summary, the content of this specification should not be understood as a limitation on the present application.

Claims

1. An application programming interface document management method, characterized in that: Applied to private cloud management platforms, including: Configure document generation tools and document parsing tools in the private cloud management platform; Based on the annotation specification provided by the document generation tool, key information in the target interface code is annotated; the key information includes: classification information of modules and components in the private cloud management platform; Deploy the annotated target interface code through a pre-configured target pipeline, and use the document generation tool to generate a corresponding target interface document based on the key information; The target interface document is parsed by the document parsing tool and displayed in an HTML page; when displaying the target interface document, the document parsing tool provides a function of filtering and viewing based on the key information.

2. The method for managing application programming interface documents according to claim 1, characterized in that: Based on the annotation specifications provided by the document generation tool, key information in the target interface code is annotated, including: Use the decoration structure to package the return data of the interface in the target interface code to generate a JSON structure; The return data is annotated based on the annotation format provided by the document generation tool, and the name, function, description, parameters, request of the target interface code and the classification information of each module and component in the private cloud management platform are annotated; wherein the classification information is annotated based on the custom annotation format provided by the document generation tool.

3. The method for managing application programming interface documents according to claim 2, characterized in that: Before marking the classification information of the target interface code, it also includes: Using the extended syntax provided by the document parsing tool, define all optional classification items in the target interface code; The classification information of the target interface code is specifically marked as follows: Based on the custom annotation format provided by the document generation tool, select at least one item from all optional classification items for annotation.

4. The method for managing application programming interface documents according to claim 1, characterized in that: The target interface code marked by the pre-configured target pipeline is deployed, and the document generation tool is used to generate a corresponding target interface document based on the key information, including: Push the annotated target interface code to the code repository and store it in a specified directory as the latest version of the interface code; Triggering the target pipeline to start code deployment of the target interface code; the code deployment includes the following operations: pulling code, building an image container, testing code, and deploying to a production environment; After pulling the code, the document generation tool is called to extract the key information marked in the target interface code, and the target interface document is generated based on the key information.

5. The method for managing application programming interface documents according to claim 4, characterized in that: Parsing the target interface document by the document parsing tool and displaying it in an HTML page includes: After building the image container, open the corresponding HTML page through the address provided by the document parsing tool; The script of the document parsing tool is loaded to parse and display the target interface document.

6. The method for managing application programming interface documents according to claim 4, characterized in that: The marked target interface code is pushed to the code repository and stored in the specified directory as the latest version of the interface code, including: In the case where the target interface code does not carry a version number, using the target interface code to overwrite the file with the same name in the specified directory; In the case where the target interface code carries a version number, the file with the same name in the designated directory is retained when the target interface code is stored.

7. The method for managing application programming interface documents according to claim 4, characterized in that: Also includes: Configuring a historical version query interface in the private cloud management platform; Based on the interface name obtained by the historical version query interface, query the version information of all interface documents corresponding to the interface name in the specified directory and display them; Configuring a document query interface in the private cloud management platform; Based on the interface name and version number obtained by the document query interface, obtain the corresponding interface document in the specified directory, and use the document parsing tool to parse and display it; A document comparison interface is configured in the private cloud management platform; based on two different version information obtained by the document comparison interface, two corresponding interface documents are obtained; Compare the differences between the two interface documents, generate a difference report based on the differences, and display it.

8. The method for managing application programming interface documents according to claim 7, characterized in that: Based on the two different version information obtained by the document comparison interface, two corresponding interface documents are obtained; Compare the differences between the two interface documents, generate and display a difference report based on the differences, including: Based on the two versions of information, obtain the corresponding two versions of interface documents from the specified directory; Use the Swagger parser to obtain element information of the two versions of the interface documents; the element information includes: mapping information, parameter information, attribute information, node information and class information; Compare the element information of the two versions of the interface documents, determine the element information updated by the newer version of the interface document relative to the old version, and generate and display a difference report; The difference report is displayed on an HTML page through an HTML renderer.

9. The method for managing application programming interface documents according to claim 7, characterized in that: After obtaining the interface name and version number based on the document query interface and obtaining the corresponding interface document in the specified directory, the method further includes: The document query interface is called by a third-party document system to obtain and parse the interface document, and the interface document is displayed in an interactive interface of the third-party document system.

10. An application programming interface document management device, used to execute the method according to any one of claims 1 to 9, comprising: An installation module is configured to configure a document generation tool and a document parsing tool in a private cloud management platform; A marking module, configured to mark key information in the target interface code based on the annotation specification provided by the document generation tool; The key information includes: classification information of modules and components in the private cloud management platform; A deployment module is configured to deploy the target interface code marked by a pre-configured target pipeline, and use the document generation tool to generate a corresponding target interface document based on the key information; The document viewing module is configured to parse the target interface document through the document parsing tool and display it in an HTML page; when displaying the target interface document, the document parsing tool provides a function of filtering and viewing based on the key information.

Images