API documentation generation methods, devices, electronic devices, and readable storage media
Through the automated API document generation method, interface feature information in the code base is extracted and populated into the Markdown template, solving the problems of inefficient and error-prone generation of existing API documents, and achieving fast and accurate API document generation.
Patent Information
- Application Number
- CN202411705736.9
- Authority / Receiving Office
- CN · China
- Patent Type
- Applications(China)
- Current Assignee / Owner
- Filing Date
- 2024-11-26
- Publication Date
- 2025-04-08
AI Technical Summary
Existing API document generation methods are inefficient and prone to errors, especially in complex scenarios, manually writing API documents is time-consuming and prone to missing parameters or introducing errors.
By obtaining the target industry code base, we can determine whether the interface contains comments. If not, add comments. Extract the interface's feature information from the code and comments, including interface name, description, request and response parameters, and fill this information into the preset Markdown document template to generate a Markdown format API document.
It realizes the rapid and accurate generation of API documents, reduces the possibility of manual writing errors, and improves development efficiency and software quality.
Smart Images
Figure CN119781819A_ABST
Abstract
Description
Technical Field
[0001] The embodiments of the present application relate to the field of software development technology, and in particular to an API document generation method, device, electronic device, and computer-readable storage medium. Background Art
[0002] In today's era of rapid development of computer technology, the efficient operation of businesses in various industries is highly dependent on information technology, and API (application programming interface) plays a key role in the interaction between different platforms and systems, and is of great significance to the development, integration and use of software systems in various industries. Specifically, the accurate generation and maintenance of API documents is a key link to ensure the normal operation of the system and the expansion of functions. Developers need to correctly develop programs that call APIs based on API documents in order to better use APIs to complete related operations of various business systems, such as querying room information, booking rooms, processing customer orders, etc.
[0003] However, there are many shortcomings in the existing API document generation methods. Among them, manual writing is a widely used but inefficient method. In the process of manually writing API documents, developers need to sort out the various functions of the API, request and response parameters, error handling mechanisms and other information in detail. This process is extremely time-consuming, especially in complex scenarios (such as hotel business scenarios), which may involve a large number of APIs with different functions. Moreover, manual writing will inevitably introduce errors, which may include omissions or errors in parameter information. These problems will affect development efficiency and software quality. Therefore, there is an urgent need for a more efficient and accurate API document generation method to meet the needs of industry software development for API documentation. Summary of the invention
[0004] The embodiments of the present application provide an API document generation method, device, electronic device and computer-readable storage medium, which can achieve the purpose of quickly and accurately generating API documents.
[0005] An embodiment of the present application provides, on one hand, a method for generating an API document, including:
[0006] Obtain a target industry code library, and determine whether a target interface in the target industry code library contains comments;
[0007] If the target interface in the target industry code library does not contain comments, add comments to the target interface;
[0008] Extracting characteristic information of the target interface from the codes and comments in the target industry code base, the characteristic information including interface name, interface description, request parameters and response parameters;
[0009] Fill the method information into the preset Markdown document template to obtain the API document for the target industry in Markdown format.
[0010] The present application also provides an API document generation device, including:
[0011] A code acquisition module is used to acquire a target industry code library and determine whether a target interface in the target industry code library contains comments;
[0012] An annotation adding module is used to add annotations to the target interface if the target interface in the target industry code library does not contain annotations;
[0013] An information extraction module, used to extract characteristic information of the target interface from the codes and comments in the target industry code library, wherein the characteristic information includes an interface name, an interface description, request parameters, and response parameters;
[0014] The document generation module is used to fill the method information into a preset Markdown document template to obtain an API document in Markdown format for the target industry.
[0015] On the one hand, an embodiment of the present application also provides an electronic device, including: a memory and a processor; the memory stores executable program code; the processor coupled to the memory calls the executable program code stored in the memory to execute the API document generation method provided in the above embodiment.
[0016] On the one hand, an embodiment of the present application further provides a computer-readable storage medium on which a computer program is stored. When the computer program is executed by a processor, the API document generation method provided in the above embodiment is executed.
[0017] It can be seen from the above-mentioned embodiments of the present application that the target industry code library is obtained, and it is determined whether the target interface in the target industry code library contains comments; if the target interface in the target industry code library does not contain comments, add comments to the target interface; extract the characteristic information of the target interface from the code and comments in the target industry code library, and the characteristic information includes the interface name, interface description, request parameters and response parameters; fill the method information into the preset Markdown document template to obtain the API document for the target industry in Markdown format. This embodiment fills the extracted characteristic information into the preset Markdown document template, and then generates an API document for the target industry in Markdown format, which can be automatically generated without manual writing by developers, reducing the possibility of errors in manual writing and achieving the purpose of quickly and accurately generating API documents. BRIEF DESCRIPTION OF THE DRAWINGS
[0018] In order to more clearly illustrate the embodiments of the present application or the technical solutions in the prior art, the following briefly introduces the drawings required for use in the embodiments or the description of the prior art. Obviously, the drawings described below are some embodiments of the present invention. For ordinary technicians in this field, other drawings can be obtained based on these drawings without paying creative labor.
[0019] Figure 1 A flowchart of an implementation method of an API document generation method provided in an embodiment of the present application;
[0020] Figure 2 A schematic diagram of the structure of an API document generation device provided in one embodiment of the present application;
[0021] Figure 3 A schematic diagram of the hardware structure of an electronic device provided in one embodiment of the present application. DETAILED DESCRIPTION
[0022] In order to make the purpose, technical solution and advantages of the embodiments of the present application clearer, the technical solution in the embodiments of the present application will be clearly and completely described below in conjunction with the drawings in the embodiments of the present application. Obviously, the described embodiments are part of the embodiments of the present invention, not all of the embodiments. Based on the embodiments of the present invention, all other embodiments obtained by ordinary technicians in this field without creative work are within the scope of protection of the present invention.
[0023] See also Figure 1 , Figure 1 The following is a flowchart of an implementation of an API document generation method provided in an embodiment of the present application. The method can be applied to electronic devices, such as Figure 1 As shown, the method specifically includes:
[0024] Step S11, obtaining a target industry code library, and determining whether a target interface in the target industry code library contains comments.
[0025] In this embodiment, the target industry code library may refer to a code library for a certain industry. For example, the target industry may be the hotel industry, the air ticket booking industry, the cruise booking industry, the travel booking industry, the catering booking industry, the movie industry, etc.
[0026] In this embodiment, if there are multiple methods in the target industry code library, it is determined whether the target interface in the target industry code library contains comments. The target interface may be all methods or part of the methods in the target industry code library.
[0027] Further, in an optional embodiment of the present invention, before determining whether the target interface in the target industry code library contains comments, the method further includes:
[0028] The method names of all methods in the target industry code library are matched with the method names in the preset document, and the methods corresponding to the matched method names are determined to be the target interface.
[0029] In this embodiment, the preset document lists the method names that need to be annotated and for which an API is to be generated. Then, the method names of all methods in the target industry code base are matched with the method names in the preset document. Specifically, it is queried whether there are method names in the preset document among the method names of all methods in the target industry code base, and the method names in the target industry code base that are consistent with the method names in the preset document are determined as matching method names.
[0030] Further, in an optional embodiment of the present invention, before determining whether the target interface in the target industry code library contains comments, the method further includes:
[0031] It is determined whether there is a specific identifier in the code line in the target industry code library. If there is a specific identifier, it is determined that the method to which the code line where the specific identifier belongs is the target interface.
[0032] The specific identifier may be preset.
[0033] Furthermore, in an optional embodiment of the present invention, the target industry is the hotel industry, and the target interface includes guest room management related methods and customer information management related methods.
[0034] The determining whether the target interface in the target industry code library contains comments includes: determining whether there is a comment mark in the target interface in the target industry code library, and if there is a comment mark, determining that the target interface contains comments.
[0035] Specifically, the comment mark can be " / / / ". For example, if there is a webapi interface, which is used to calculate the total price of a hotel room, if " / / / " is detected in the relevant code line of the webapi interface, it is determined that the webapi interface has a mark.
[0036] Furthermore, in an optional embodiment of the present invention, before obtaining the target industry code library, the method further includes:
[0037] In response to the API document generation instruction triggered by the version management library after detecting the code update, the operation of obtaining the target industry code library is performed.
[0038] In this embodiment, when the version management library detects that a new code version is updated, it issues an API document generation instruction. In response to the instruction, it directly executes the operation of obtaining the target industry code library, which can ensure the update of the document and the code, and reduce the risk of inconsistency between the document and the code.
[0039] Further, in an optional embodiment of the present invention, before determining whether the target interface in the target industry code library contains comments, the method further includes:
[0040] Identify incremental code and modified code contained in the target industry code base;
[0041] The incremental code and the method included in the modified code are determined to be the target interface.
[0042] In this embodiment, incremental code refers to code generated due to the addition of new functions, etc., which does not exist in the previous code version. Modified code refers to code involved due to the modification of old functions, etc., which already existed in the previous code version but was modified in the new version.
[0043] Specifically, the target industry code base can be matched with the code in the version management library to determine the incremental code and modified code contained in the target industry code base, or the incremental code and modified code contained in the target industry code base can be determined by receiving the difference check result returned by the version management library. If only incremental code is included, only the incremental code is judged whether it contains comments, and then the API document generation operation is performed.
[0044] In an optional embodiment of the present invention, API documentation may be generated only for incremental code.
[0045] In another optional embodiment of the present invention, API documents can be generated for incremental code and modified code through the operation of the embodiment of the method of the present invention, and non-incremental code and non-modified code are directly copied from existing API documents (such as previously generated API documents) to the generated API documents, so that comprehensive and accurate API documents can be quickly generated.
[0046] Step S12: if the target interface in the target industry code library does not contain comments, add comments to the target interface.
[0047] In this embodiment, if the target interface in the target industry code library contains comments, the operation of step S13 is directly executed.
[0048] In this embodiment, comments can be added by means of code structure analysis tools, function name matching algorithms, etc.
[0049] Further, in an optional embodiment of the present invention, the adding annotation to the target interface includes:
[0050] A pre-trained annotation prediction model is used to generate annotations for the target interface. The pre-trained annotation prediction model is built based on Transformer and includes at least two loss functions, one of which is used to calculate the difference between the predicted annotation and the actual annotation, and the other is used to calculate the difference between the predicted annotation and the standard description in the standard document library. Furthermore, the data of the model during training is a combination of code data and the standard description in the standard document library.
[0051] In this embodiment, the pre-trained annotation prediction model can be built based on Transformer, which means that the pre-trained model is a model of Transformer architecture.
[0052] During training, first, obtain a large amount of code data and annotation data, for example, from GitHub, internal corporate code bases, hotel reservation systems, room management systems, customer information management systems, etc. Obtain the content corresponding to the code and annotations in the standard document library as standard descriptions, for example, extract the meaning of different reservation states from the hotel reservation process document, and extract the correspondence between room types and prices from the room information interface specification document.
[0053] Secondly, the acquired data and codes are cleaned and formatted.
[0054] Next, the code is segmented according to the grammatical structure and keywords of the corresponding language, each segmented word is converted into a corresponding vector representation, and the standard description in the standard document library is vectorized so that the content obtained after code segmentation and the standard description in the standard document library are combined to form an input vector sequence. This allows the information in the standard document library to be integrated into the model input or training process during the model training process, improving the accuracy and standardization of the prediction annotations.
[0055] Among them, the standard document library can include key information extracted from API specification documents such as hotel business process documents, such as business process descriptions, interface function descriptions, data format requirements, etc.
[0056] Then, the input vector sequence is used to train the pre-built Transformer architecture model to obtain a pre-trained annotation prediction model. Specifically, supervised learning can be performed.
[0057] In this embodiment, at least two loss functions are used, one of which is used to calculate the difference between the predicted annotation and the actual annotation, and the other is used to calculate the difference between the predicted annotation and the standard description in the standard document library, and the parameters of the model can be continuously adjusted by the stochastic gradient descent algorithm, thereby further improving the accuracy and practicality of the annotation.
[0058] Step S13, extracting characteristic information of the target interface from the codes and comments in the target industry code library, wherein the characteristic information includes an interface name, an interface description, request parameters, and response parameters.
[0059] In this embodiment, feature information of the target interface may be extracted from the codes and comments in the target industry code library by means of regular expression matching.
[0060] Specifically, the characteristic information may include not only the interface name, interface description, request parameters, and response parameters, but also information such as exception handling methods.
[0061] For example, the extracted feature information includes the following information:
[0062] Interface name: roomBooking
[0063] Interface description: Create a reservation order: Create a new room reservation order based on the check-in date, check-out date, room type and other information provided by the customer.
[0064] Request method: POST
[0065] Request parameters:
[0066] checkInDate: Date type, required, check-in date.
[0067] checkOutDate: Date type, required, check-out date.
[0068] roomType: string type, required, room type.
[0069] customerName: string type, required, customer name.
[0070] customerContact: string type, required, customer contact information.
[0071] Response parameters:
[0072] orderId: integer type, the ID of the newly created order.
[0073] status: string type, order creation status, such as "success" or "fail".
[0074] Error handling:
[0075] 400: Indicates that the request parameters are incorrect.
[0076] 401: Indicates unauthorized access.
[0077] 500: indicates an internal server error.
[0078] error message:
[0079] When a 400 error code is returned, the error message is: The request parameters are missing or the format is incorrect. Please check the input parameters.
[0080] When a 401 error code is returned, the error message is: Unauthorized access, please provide valid authentication information.
[0081] When a 500 error code is returned, the error message is: Internal server error, please try again later.
[0082] The above is only an example of the extracted feature information. The extracted feature information may also include more content such as implementation logic in other optional embodiments.
[0083] Step S14, filling the method information into a preset Markdown document template to obtain an API document for the target industry in Markdown format.
[0084] Specifically, the extracted method information can be filled in the form of placeholders to ensure a uniform document style. That is, the extracted method information is accurately filled in the position where the placeholder is located, thereby generating a document with a uniform style.
[0085] Further, in an optional embodiment of the present invention, after obtaining the API document for the target industry in Markdown format, the method further includes:
[0086] Performing at least two of grammar and spelling checking, ambiguity elimination, and text consistency checking on the API document for the target industry; or
[0087] The knowledge graph is used to identify the calling relationships between the APIs in the API document, and the calling relationships are added to the API document.
[0088] Specifically, the knowledge graph is a structured knowledge representation method, which includes nodes (entities) and edges (relationships). Specifically, you can obtain existing business-related API documents, business processes and other related information to pre-build the knowledge graph, and then perform entity extraction, relationship extraction and build the graph structure.
[0089] For example, through the relationship query in the knowledge graph, it is found that a "get available rooms" API may depend on the "get user information" and "query room type" APIs. Then add this call relationship in the generated API document.
[0090] Through this embodiment, it is possible to check whether a clear and understandable description is generated, whether important information is omitted, and whether there is repeated or lengthy content, thereby further improving the readability of the document and improving the document quality.
[0091] Further, in an optional embodiment of the present invention, after obtaining the API document for the target industry in Markdown format, the method further includes:
[0092] The API document for the target industry is translated using a translation engine to obtain a translated API document.
[0093] Specifically, during translation, the existing machine translation engine can be directly called to translate the API document.
[0094] Specifically, you can identify specific annotations to determine which parts need to be translated, or you can identify specific files, directories, or code blocks to determine which parts need to be translated. For example, you can translate the description and error message parts of an API document into different languages for users from different countries.
[0095] Further, in an optional embodiment of the present invention, the step of translating the API document for the target industry using a translation engine includes:
[0096] Identify abbreviations and target terms in API documentation for the target industry;
[0097] The abbreviations are replaced by using an abbreviation library and the target terms are replaced by using a term library to obtain an API document to be translated;
[0098] The API document to be translated is translated using a translation engine to obtain a translated API document.
[0099] In this embodiment, all abbreviations in the API document can be identified. The target term can be all the terms in the API document or part of the data. For example, the target term is a word with different semantics in different industries.
[0100] Specifically, the abbreviations and target data may be identified by keyword matching or regular expressions, and the abbreviations and target terms that need to be replaced may also be determined based on the query translation mapping table.
[0101] In this embodiment, by first translating the abbreviations and target terms and then using the translation engine to translate, the accuracy of the translation can be improved, thereby avoiding the problem of inaccurate translation caused by abbreviations and terminology problems.
[0102] Further, in an optional embodiment of the present invention, after obtaining the API document for the target industry in Markdown format, the method further includes:
[0103] When receiving a command to view the generated document, displaying a browsing interface, wherein the API document is displayed in the browsing interface; or
[0104] When a modification and generation document instruction is received, an editable interface is displayed, in which the editable API document is displayed.
[0105] In this embodiment, the command to view the generated document may be triggered by the user clicking a “view button.” Similarly, the command to modify the generated document may also be triggered by the user clicking an “edit button.”
[0106] Through this embodiment, the user can view the style and content of the document after the API document is generated. At the same time, the user can also edit and optimize the generated API document.
[0107] In an embodiment of the present application, a target industry code library is obtained, and it is determined whether the target interface in the target industry code library contains comments; if the target interface in the target industry code library does not contain comments, comments are added to the target interface; characteristic information of the target interface is extracted from the code and comments in the target industry code library, and the characteristic information includes interface name, interface description, request parameters, and response parameters; the method information is filled into a preset Markdown document template to obtain an API document in Markdown format for the target industry. This embodiment fills the extracted characteristic information into a preset Markdown document template, and then generates an API document in Markdown format for the target industry. It can be automatically generated without manual writing by developers, which reduces the possibility of errors in manual writing and achieves the purpose of quickly and accurately generating API documents.
[0108] See also Figure 2 , a schematic diagram of the structure of an API document generation device provided in an embodiment of the present application. For ease of explanation, only the parts related to the embodiment of the present application are shown. The device can be set in an electronic device. The device includes:
[0109] The code acquisition module 201 is used to acquire a target industry code library and determine whether a target interface in the target industry code library contains comments.
[0110] In this embodiment, the target industry code library may refer to a code library for a certain industry. For example, the target industry may be the hotel industry, the air ticket booking industry, the cruise booking industry, the travel booking industry, the catering booking industry, the movie industry, etc.
[0111] In this embodiment, if there are multiple methods in the target industry code library, it is determined whether the target interface in the target industry code library contains comments. The target interface may be all methods or part of the methods in the target industry code library.
[0112] Furthermore, in an optional embodiment of the present invention, the API document generating device further includes a determining module, and the determining module is used to:
[0113] Before determining whether the target interface in the target industry code library contains comments, the method names of all methods in the target industry code library are matched with the method names in the preset document to determine that the method corresponding to the matched method name is the target interface.
[0114] In this embodiment, the preset document lists the method names that need to be annotated and for which an API is to be generated. Then, the method names of all methods in the target industry code base are matched with the method names in the preset document. Specifically, it is queried whether there are method names in the preset document among the method names of all methods in the target industry code base, and the method names in the target industry code base that are consistent with the method names in the preset document are determined as matching method names.
[0115] Furthermore, in an optional embodiment of the present invention, the determining module is further configured to:
[0116] Before determining whether the target interface in the target industry code library contains comments, determine whether there is a specific identifier in the code line in the target industry code library. If there is a specific identifier, determine that the method to which the code line where the specific identifier belongs is the target interface.
[0117] The specific identifier may be preset.
[0118] Furthermore, in an optional embodiment of the present invention, the target industry is the hotel industry, and the target interface includes guest room management related methods and customer information management related methods.
[0119] In this embodiment, the code acquisition module determines whether there is a comment mark in the target interface in the target industry code library, and if there is a comment mark, it is determined that the target interface contains comments.
[0120] Specifically, the comment mark can be " / / / ". For example, if there is a webapi interface, which is used to calculate the total price of a hotel room, if " / / / " is detected in the relevant code line of the webapi interface, it is determined that the webapi interface has a mark.
[0121] Furthermore, in an optional embodiment of the present invention, the API document generating device further includes a trigger module, wherein the trigger module is used to:
[0122] Before acquiring the target industry code library, in response to the API document generation instruction triggered by the version management library after detecting the code update, the code acquisition module is triggered to execute the operation of acquiring the target industry code library.
[0123] In this embodiment, when the version management library detects that a new code version is updated, it issues an API document generation instruction. In response to the instruction, it directly executes the operation of obtaining the target industry code library, which can ensure the update of the document and the code, and reduce the risk of inconsistency between the document and the code.
[0124] Furthermore, in an optional embodiment of the present invention, the code acquisition module is also used for:
[0125] Before determining whether the target interface in the target industry code library contains annotations, identifying incremental codes and modified codes contained in the target industry code library;
[0126] The incremental code and the method included in the modified code are determined to be the target interface.
[0127] In this embodiment, incremental code refers to code generated due to the addition of new functions, etc., which does not exist in the previous code version. Modified code refers to code involved due to the modification of old functions, etc., which already existed in the previous code version but was modified in the new version.
[0128] Specifically, the target industry code base can be matched with the code in the version management library to determine the incremental code and modified code contained in the target industry code base, or the incremental code and modified code contained in the target industry code base can be determined by receiving the difference check result returned by the version management library. If only incremental code is included, only the incremental code is judged whether it contains comments, and then the API document generation operation is performed.
[0129] In an optional embodiment of the present invention, API documentation may be generated only for incremental code.
[0130] In another optional embodiment of the present invention, API documents can be generated for incremental code and modified code through the operation of the embodiment of the method of the present invention, and non-incremental code and non-modified code are directly copied from existing API documents (such as previously generated API documents) to the generated API documents, so that comprehensive and accurate API documents can be quickly generated.
[0131] The annotation adding module 202 is used to add annotations to the target interface if the target interface in the target industry code library does not contain annotations.
[0132] In this embodiment, if the target interface in the target industry code library contains comments, the information extraction module 203 is directly called to perform the operation.
[0133] In this embodiment, comments can be added by means of code structure analysis tools, function name matching algorithms, etc.
[0134] Further, in an optional embodiment of the present invention, the adding annotation to the target interface includes:
[0135] A pre-trained annotation prediction model is used to generate annotations for the target interface. The pre-trained annotation prediction model is built based on Transformer and includes at least two loss functions, one of which is used to calculate the difference between the predicted annotation and the actual annotation, and the other is used to calculate the difference between the predicted annotation and the standard description in the standard document library. Furthermore, the data of the model during training is a combination of code data and the standard description in the standard document library.
[0136] In this embodiment, the pre-trained annotation prediction model can be built based on Transformer, which means that the pre-trained model is a model of Transformer architecture.
[0137] During training, first, obtain a large amount of code data and annotation data, for example, from GitHub, internal corporate code bases, hotel reservation systems, room management systems, customer information management systems, etc. Obtain the content corresponding to the code and annotations in the standard document library as standard descriptions, for example, extract the meaning of different reservation states from the hotel reservation process document, and extract the correspondence between room types and prices from the room information interface specification document.
[0138] Secondly, the acquired data and codes are cleaned and formatted.
[0139] Next, the code is segmented according to the grammatical structure and keywords of the corresponding language, each segmented word is converted into a corresponding vector representation, and the standard description in the standard document library is vectorized so that the content obtained after code segmentation and the standard description in the standard document library are combined to form an input vector sequence. This allows the information in the standard document library to be integrated into the model input or training process during the model training process, improving the accuracy and standardization of the prediction annotations.
[0140] Among them, the standard document library can include key information extracted from API specification documents such as hotel business process documents, such as business process descriptions, interface function descriptions, data format requirements, etc.
[0141] Then, the input vector sequence is used to train the pre-built Transformer architecture model to obtain a pre-trained annotation prediction model. Specifically, supervised learning can be performed.
[0142] In this embodiment, at least two loss functions are used, one of which is used to calculate the difference between the predicted annotation and the actual annotation, and the other is used to calculate the difference between the predicted annotation and the standard description in the standard document library, and the parameters of the model can be continuously adjusted by the stochastic gradient descent algorithm, thereby further improving the accuracy and practicality of the annotation.
[0143] The information extraction module 203 is used to extract characteristic information of the target interface from the codes and comments in the target industry code library, wherein the characteristic information includes interface name, interface description, request parameters and response parameters.
[0144] In this embodiment, feature information of the target interface may be extracted from the codes and comments in the target industry code library by means of regular expression matching.
[0145] Specifically, the characteristic information may include not only the interface name, interface description, request parameters, and response parameters, but also information such as exception handling methods.
[0146] For example, the extracted feature information includes the following information:
[0147] Interface name: roomBooking
[0148] Interface description: Create a reservation order: Create a new room reservation order based on the check-in date, check-out date, room type and other information provided by the customer.
[0149] Request method: POST
[0150] Request parameters:
[0151] checkInDate: Date type, required, check-in date.
[0152] checkOutDate: Date type, required, check-out date.
[0153] roomType: string type, required, room type.
[0154] customerName: string type, required, customer name.
[0155] customerContact: string type, required, customer contact information.
[0156] Response parameters:
[0157] orderId: integer type, the ID of the newly created order.
[0158] status: string type, order creation status, such as "success" or "fail".
[0159] Error handling:
[0160] 400: Indicates that the request parameters are incorrect.
[0161] 401: Indicates unauthorized access.
[0162] 500: indicates an internal server error.
[0163] error message:
[0164] When a 400 error code is returned, the error message is: The request parameters are missing or the format is incorrect. Please check the input parameters.
[0165] When a 401 error code is returned, the error message is: Unauthorized access, please provide valid authentication information.
[0166] When a 500 error code is returned, the error message is: Internal server error, please try again later.
[0167] The above is only an example of the extracted feature information. The extracted feature information may also include more content such as implementation logic in other optional embodiments.
[0168] The document generation module 204 is used to fill the method information into a preset Markdown document template to obtain an API document for the target industry in Markdown format.
[0169] Specifically, the extracted method information can be filled in the form of placeholders to ensure a uniform document style. That is, the extracted method information is accurately filled in the position where the placeholder is located, thereby generating a document with a uniform style.
[0170] Furthermore, in an optional embodiment of the present invention, the document generation module is also used to:
[0171] After obtaining the API document for the target industry in Markdown format, perform at least two of grammar and spelling checking, ambiguity elimination, and text consistency checking on the API document for the target industry, or use a knowledge graph to identify the calling relationship between APIs in the API document and add the calling relationship to the API document.
[0172] Specifically, the knowledge graph is a structured knowledge representation method, which includes nodes (entities) and edges (relationships). Specifically, you can obtain existing business-related API documents, business processes and other related information to pre-build the knowledge graph, and then perform entity extraction, relationship extraction and build the graph structure.
[0173] For example, through the relationship query in the knowledge graph, it is found that a "get available rooms" API may depend on the "get user information" and "query room type" APIs. Then add this call relationship in the generated API document.
[0174] Through this embodiment, it is possible to check whether a clear and understandable description is generated, whether important information is omitted, and whether there is repeated or lengthy content, thereby further improving the readability of the document and improving the document quality.
[0175] Furthermore, in an optional embodiment of the present invention, the document generation module is also used to:
[0176] After obtaining the API document for the target industry in Markdown format, the API document for the target industry is translated using a translation engine to obtain a translated API document.
[0177] Specifically, during translation, the existing machine translation engine can be directly called to translate the API document.
[0178] Specifically, you can identify specific annotations to determine which parts need to be translated, or you can identify specific files, directories, or code blocks to determine which parts need to be translated. For example, you can translate the description and error message parts of an API document into different languages for users from different countries.
[0179] Further, in an optional embodiment of the present invention, the step of translating the API document for the target industry using a translation engine includes:
[0180] Identify abbreviations and target terms in API documentation for the target industry;
[0181] The abbreviations are replaced by using an abbreviation library and the target terms are replaced by using a term library to obtain an API document to be translated;
[0182] The API document to be translated is translated using a translation engine to obtain a translated API document.
[0183] In this embodiment, all abbreviations in the API document can be identified. The target term can be all the terms in the API document or part of the data. For example, the target term is a word with different semantics in different industries.
[0184] Specifically, the abbreviations and target data may be identified by keyword matching or regular expressions, and the abbreviations and target terms that need to be replaced may also be determined based on the query translation mapping table.
[0185] In this embodiment, by first translating the abbreviations and target terms and then using the translation engine to translate, the accuracy of the translation can be improved, thereby avoiding the problem of inaccurate translation caused by abbreviations and terminology problems.
[0186] Furthermore, in an optional embodiment of the present invention, the document generation module is also used to:
[0187] After obtaining the API document for the target industry in Markdown format, when a view generated document instruction is received, a browsing interface is displayed, in which the API document is displayed; or, when a modify generated document instruction is received, an editable interface is displayed, in which the editable API document is displayed.
[0188] In this embodiment, the command to view the generated document may be triggered by the user clicking a “view button.” Similarly, the command to modify the generated document may also be triggered by the user clicking an “edit button.”
[0189] Through this embodiment, the user can view the style and content of the document after the API document is generated. At the same time, the user can also edit and optimize the generated API document.
[0190] In an embodiment of the present application, a target industry code library is obtained, and it is determined whether the target interface in the target industry code library contains comments; if the target interface in the target industry code library does not contain comments, comments are added to the target interface; characteristic information of the target interface is extracted from the code and comments in the target industry code library, and the characteristic information includes interface name, interface description, request parameters, and response parameters; the method information is filled into a preset Markdown document template to obtain an API document in Markdown format for the target industry. This embodiment fills the extracted characteristic information into a preset Markdown document template, and then generates an API document in Markdown format for the target industry. It can be automatically generated without manual writing by developers, which reduces the possibility of errors in manual writing and achieves the purpose of quickly and accurately generating API documents.
[0191] See also Figure 3 , a schematic diagram of the hardware structure of an electronic device provided in one embodiment of the present application.
[0192] Exemplarily, the electronic device may be any of various types of computer system devices that are mobile or portable and perform wireless communication. Specifically, the electronic device may be a personal computer or a server.
[0193] The electronic device may also be any one of a plurality of electronic devices including, but not limited to, cellular phones, smart phones, other wireless communication devices.
[0194] In some cases, an electronic device can perform multiple functions (eg, play music, display video, store pictures).
[0195] like Figure 3 As shown, the electronic device 10 may include a control circuit, which may include a storage and processing circuit 30. The storage and processing circuit 30 may include a memory, such as a hard disk drive memory, a non-volatile memory (such as a flash memory or other electronically programmable memory with limited deletion for forming a solid-state drive, etc.), a volatile memory (such as a static or dynamic random access memory, etc.), etc., which is not limited in the embodiment of the present application. The processing circuit in the storage and processing circuit 30 can be used to control the operation of the electronic device 10. The processing circuit can be implemented based on one or more microprocessors, microcontrollers, digital signal processors, baseband processors, power management units, audio codec chips, application-specific integrated circuits, display driver integrated circuits, etc.
[0196] The storage and processing circuit 30 can be used to run software in the electronic device 10, such as an Internet browsing application, an email application, a media playback application, an operating system function, etc. These software can be used to perform some control operations, such as image acquisition based on a camera, touch event detection based on a touch sensor, functions associated with displaying information on multiple (e.g., layered) displays, operations associated with performing wireless communication functions, operations associated with collecting and generating audio signals, control operations associated with collecting and processing button press event data, and other functions in the electronic device 10, etc., which are not limited in the embodiments of the present application.
[0197] Furthermore, the memory stores an executable program code, and the processor coupled to the memory calls the executable program code stored in the memory to execute the above Figure 1 The API document generation method described in the illustrated embodiment.
[0198] The executable program code includes the above Figure 2 The various modules in the API document generation device described in the illustrated embodiment, for example: a code acquisition module, an annotation adding module, an information extraction module and a document generation module.
[0199] The electronic device 10 may further include an input-output circuit 42. The input-output circuit 42 may be used to enable the electronic device 10 to input and output data, that is, to allow the electronic device 10 to receive data from an external device and also to allow the electronic device 10 to output data from the electronic device 10 to an external device. The input-output circuit 42 may further include a sensor 32. The sensor 32 may include an ambient light sensor, a proximity sensor based on light and capacitance, a touch sensor (e.g., based on a light touch sensor and / or a capacitive touch sensor, wherein the touch sensor may be part of a touch display screen or may be used independently as a touch sensor structure), an acceleration sensor, and other sensors.
[0200] The input-output circuit 42 may also include one or more displays, such as the display 14. The display 14 may include a liquid crystal display, an organic light-emitting diode display, an electronic ink display, a plasma display, a display using other display technologies, or a combination of several of them. The display 14 may include a non-touch sensor, or may include a touch sensor array (i.e., the display 14 may be a touch display screen). The touch sensor may be a capacitive touch sensor formed by an array of transparent touch sensor electrodes (e.g., indium tin oxide (ITO) electrodes), or may be a touch sensor formed using other touch technologies, such as sonic touch, pressure-sensitive touch, resistive touch, optical touch, etc., which is not limited in the embodiments of the present application.
[0201] The electronic device 10 may also include an audio component 36. The audio component 36 may be used to provide audio input and output functions for the electronic device 10. The audio component 36 in the electronic device 10 may include a speaker, a microphone, a buzzer, a tone generator, and other components for generating and detecting sound.
[0202] The communication circuit 38 can be used to provide the electronic device 10 with the ability to communicate with external devices. The communication circuit 38 may include analog and digital input / output interface circuits, and wireless communication circuits based on radio frequency signals and / or optical signals. The wireless communication circuit in the communication circuit 38 may include a radio frequency transceiver circuit, a power amplifier circuit, a low noise amplifier, a switch, a filter, and an antenna. For example, the wireless communication circuit in the communication circuit 38 may include a circuit for supporting near field communication (NFC) by transmitting and receiving near field coupled electromagnetic signals. For example, the communication circuit 38 may include a near field communication antenna and a near field communication transceiver. The communication circuit 38 may also include a cellular phone transceiver and antenna, a wireless local area network transceiver circuit and antenna, etc.
[0203] The electronic device 10 may further include a battery, power management circuits and other input / output units 40. The input / output units 40 may include buttons, joysticks, click wheels, scroll wheels, touch pads, keypads, keyboards, cameras, light emitting diodes and other status indicators.
[0204] A user may input commands through the input-output circuit 42 to control the operation of the electronic device 10 , and may use the output data of the input-output circuit 42 to receive status information and other outputs from the electronic device 10 .
[0205] Furthermore, an embodiment of the present invention further provides a computer-readable storage medium, which may be disposed in the electronic device in the above embodiments. The computer-readable storage medium may be the above Figure 3 The memory in the storage and processing circuit 30 in the illustrated embodiment. The computer readable storage medium stores a computer program, which, when executed by the processor, implements the aforementioned Figure 1 The API document generation method described in the illustrated embodiment. Further, the computer storable medium may also be a U disk, a mobile hard disk, a read-only memory (ROM), a RAM, a magnetic disk or an optical disk, and other media that can store program codes.
[0206] It should be noted that, for the convenience of description, the aforementioned method embodiments are all described as a series of action combinations, but those skilled in the art should be aware that the present invention is not limited by the described action sequence, because according to the present invention, certain steps can be performed in other sequences 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 modules involved are not necessarily required by the present invention.
[0207] In the above embodiments, the description of each embodiment has its own emphasis. For parts that are not described in detail in a certain embodiment, reference can be made to the relevant descriptions of other embodiments.
[0208] The above is a description of the API document generation method, device and computer-readable storage medium provided by the present invention. For a person skilled in the art, according to the idea of the embodiments of the present invention, there may be changes in the specific implementation method and application scope. In summary, the content of this specification should not be understood as a limitation of the present invention.
Claims
1. A method for generating an API document, characterized in that: The method comprises: Obtain a target industry code library, and determine whether a target interface in the target industry code library contains comments; If the target interface in the target industry code library does not contain comments, add comments to the target interface; Extracting characteristic information of the target interface from the codes and comments in the target industry code base, the characteristic information including interface name, interface description, request parameters and response parameters; Fill the method information into the preset Markdown document template to obtain the API document for the target industry in Markdown format.
2. The method according to claim 1, characterized in that After obtaining the API document for the target industry in Markdown format, the method further includes: Performing at least two of grammar and spelling checking, ambiguity elimination, and text consistency checking on the API document for the target industry; or The knowledge graph is used to identify the calling relationships between the APIs in the API document, and the calling relationships are added to the API document.
3. The method according to claim 1, characterized in that The adding annotation to the target interface includes: The annotations of the target interface are generated using a pre-trained annotation prediction model, which is built based on Transformer and includes at least two loss functions, one of which is used to calculate the difference between the predicted annotations and the actual annotations, and the other is used to calculate the difference between the predicted annotations and the standard descriptions in the standard document library. In addition, the data of the model during training is a combination of code data and the standard descriptions in the standard document library.
4. The method according to claim 1, characterized in that After obtaining the API document for the target industry in Markdown format, the method further includes: The API document for the target industry is translated using a translation engine to obtain a translated API document.
5. The method according to claim 4, characterized in that The using of a translation engine to translate the API document for the target industry includes: Identify abbreviations and target terms in API documentation for the target industry; The abbreviations are replaced by using an abbreviation library and the target terms are replaced by using a term library to obtain an API document to be translated; The API document to be translated is translated using a translation engine to obtain a translated API document.
6. The method according to any one of claims 1 to 5, characterized in that Before obtaining the target industry code library, the method further includes: In response to the API document generation instruction triggered by the version management library after detecting the code update, the operation of obtaining the target industry code library is performed.
7. The method according to any one of claims 1 to 5, characterized in that After obtaining the API document for the target industry in Markdown format, the method further includes: When receiving a command to view the generated document, displaying a browsing interface, wherein the API document is displayed in the browsing interface; or When a modification and generation document instruction is received, an editable interface is displayed, in which the editable API document is displayed.
8. An API document generation device, characterized in that: The device comprises: A code acquisition module is used to acquire a target industry code library and determine whether a target interface in the target industry code library contains comments; An annotation adding module is used to add annotations to the target interface if the target interface in the target industry code library does not contain annotations; An information extraction module, used to extract characteristic information of the target interface from the codes and comments in the target industry code library, wherein the characteristic information includes an interface name, an interface description, request parameters, and response parameters; The document generation module is used to fill the method information into a preset Markdown document template to obtain an API document in Markdown format for the target industry.
9. An electronic device, characterized in that: The electronic device comprises: Memory and processor; The memory stores executable program code; The processor coupled to the memory calls the executable program code stored in the memory to execute the API document generation method according to any one of claims 1 to 7.
10. A computer-readable storage medium having a computer program stored thereon, characterized in that: When the computer program is executed by a processor, the API document generation method according to any one of claims 1 to 7 is implemented.