Innotation-based document generation method and system, electronic equipment and storage medium

Abstract

The invention relates to an annotation-based document generation method and system, electronic equipment and a storage medium, and the method comprises the steps: obtaining a preset self-defined annotation as a special behavior identifier of a document generator; adopting protobuf as a description format, and defining a data structure of an API interface according to the user-defined annotation to obtain a protocol description file; analyzing the protocol description file, and generating an intermediate code conforming to an OpenAPI specification according to a user-defined annotation in the file; compiling the intermediate code to generate an API (Application Program Interface) document conforming to an OpenAPI (Open Application Program Interface) specification; and obtaining a preset compiling tool, and compiling the API document to obtain a final delivery document. According to the application, the document description is simplified and migrated into the protocol description, the document can be generated only by scanning the protocol description, the document generation time and computing resource consumption are reduced, and the document is directly generated from the protocol description, so that the consistency of the document content and the actual API definition is ensured, and the accuracy and reliability of the document are improved.

Description

Technical Field

[0001] The present application relates to the field of software development, and in particular to an annotation-based document generation method, system, electronic device and storage medium. Background Art

[0002] When building an API on the server backend, it is usually necessary to provide a description document for the API and deliver it to the API user. The user makes API calls based on the description document. Currently, the industry widely uses OpenAPI as a document delivery specification. OpenAPI is essentially a description format that describes every detail of the API in detail so that the caller can clearly and accurately understand the purpose of the API and understand information such as parameters required when calling the API.

[0003] When using go-swagger as an API document generation solution, you must insert the document description at the appropriate location of the business code you wrote. In the current business environment, protobuf is generally used for protocol description, which means that if you use go-swagger, you must maintain the consistency between the business annotations and the protocol descriptions. The annotations of the business code must be consistent with the definitions in protobuf, otherwise the document will be different from the actual content, which brings endless troubles to back-end development, and you need to worry about whether the document corresponds correctly. Therefore, the existing document generation solution not only increases the development workload and reduces work efficiency, but also increases the risk of errors. In addition, when the API changes, the relevant document annotations also need to be updated synchronously, which can easily lead to the problem of the document being out of sync with the actual API, thereby affecting the advancement of the development project. Summary of the invention

[0004] The embodiments of the present application provide an annotation-based document generation method, system, electronic device, and storage medium to at least solve the problem in the related art that existing document generation solutions have high developer workload and low efficiency.

[0005] In a first aspect, an embodiment of the present application provides a method for generating a document based on annotations, comprising:

[0006] Get the preset custom annotation as a special behavior identifier of the document generator;

[0007] Using protobuf as the description format, combining the custom annotations to define the data structure of the API interface, and obtaining a protocol description file;

[0008] Parse the protocol description file, and generate intermediate code that complies with the OpenAPI specification according to the custom annotations in the protocol description file;

[0009] Compile the intermediate code to generate API documentation;

[0010] Obtain a preset compilation tool, compile the API document, and obtain a final delivery document.

[0011] In one embodiment, the types of custom annotations include:

[0012] Authorization annotations, used to define access rights to the interface;

[0013] Hidden annotations are used to define non-public interfaces or fields;

[0014] Verification annotations are used to define data constraints for fields;

[0015] Stateless annotation, used to define that the API interface does not rely on the state information of previous requests when processing requests;

[0016] Stateful annotations are used to define that the API interface depends on the state information of previous requests when processing requests.

[0017] In one embodiment, the data structure of the API interface defined according to the custom annotation is used to obtain a protocol description file, including:

[0018] Identify and process custom annotations in protocol description files;

[0019] Create a new proto file through the pre-installed Protobuf compiler and define the data structure required by the API interface;

[0020] In the roto file, the message keyword is used to define the message type, and the message type represents the data structure of the API interface;

[0021] According to the message type, corresponding custom annotations are added to the proto file to obtain the protocol description file.

[0022] In one embodiment, the parsing of the protocol description file and generating intermediate code that complies with the OpenAPI specification according to the custom annotations in the file includes:

[0023] Obtain a parsing tool, and parse the protocol description file using the parsing tool to obtain parsing information;

[0024] A preset code template is obtained, and the code template is rendered according to the parsing information to obtain the intermediate code.

[0025] In one embodiment, compiling the intermediate code to generate an API document that complies with the OpenAPI specification includes:

[0026] Extracting an API definition from the intermediate code, including data structures of API requests and responses;

[0027] Extracting constraints and metadata based on the custom annotations;

[0028] Map the data types in the intermediate code to the data types supported by OpenAPI;

[0029] That is, generating a parameter definition in the OpenAPI format according to the data structure of the API request and response, as well as the constraints and metadata;

[0030] The parameter definition and data type are assembled in the yaml or json format of the OpenAPI specification to obtain the API document.

[0031] In a second aspect, an embodiment of the present application provides an annotation-based document generation system, characterized in that it is used to implement the annotation-based document generation method described in any of the above embodiments, including:

[0032] An annotation processor is used to obtain a preset custom annotation as a special behavior identifier of the document generator; and uses protobuf as a description format, and defines the data structure of the API interface in combination with the custom annotation to obtain a protocol description file;

[0033] A code generator, used to parse the protocol description file and generate intermediate code that complies with the OpenAPI specification according to the custom annotations in the protocol description file;

[0034] The document renderer is used to compile the intermediate code to generate API documents; and obtain a preset compilation tool to compile the API documents to obtain the final delivery document.

[0035] In one embodiment, the annotation processor includes:

[0036] Annotation processing module, used to identify and process custom annotations in protocol description files;

[0037] The protocol description generation module is used to create a new proto file through a pre-installed Protobuf compiler and define the data structure required by the API interface; in the roto file, the message keyword is used to define the message type, and the message type represents the data structure of the API interface; according to the message type, corresponding custom annotations are added to the proto file to obtain the protocol description file.

[0038] In one embodiment, the document renderer is used to compile the intermediate code, and the process of generating the API document includes:

[0039] Extract API definition from the intermediate code, including the data structure of API request and response; extract constraints and metadata according to the custom annotations; map the data types in the intermediate code to the data types supported by OpenAPI; that is, generate parameter definitions in OpenAPI format according to the data structure of the API request and response, as well as the constraints and metadata; assemble the parameter definitions and data types in the yaml or json format of the OpenAPI specification to obtain the API document.

[0040] In a third aspect, an embodiment of the present application provides a computer device comprising a memory, a processor, and a computer program stored in the memory and executable on the processor, wherein when the processor executes the computer program, the annotation-based document generation method as described in the first aspect above is implemented.

[0041] In a fourth aspect, an embodiment of the present application provides a computer-readable storage medium having a computer program stored thereon, which, when executed by a processor, implements the annotation-based document generation method as described in the first aspect above.

[0042] The annotation-based document generation method, system, electronic device, and storage medium provided in the embodiments of the present application have at least the following technical effects:

[0043] This application obtains pre-set custom annotations as special behavior identifiers of the document generator; uses protobuf as the description format, defines the data structure of the API interface according to the custom annotations, and obtains a protocol description file; parses the protocol description file, and generates intermediate code that complies with the OpenAPI specification according to the custom annotations in the file; compiles the intermediate code to generate an API document that complies with the OpenAPI specification; obtains a preset compilation tool, compiles the API document, and obtains the final delivery document, simplifies the document description and migrates it to the protocol description. The document can be generated by simply scanning the protocol description, which reduces the time and computing resource consumption of document generation. In addition, since the document is generated directly from the protocol description, the consistency of the document content with the actual API definition is ensured, thereby improving the accuracy and reliability of the document.

[0044] Details of one or more embodiments of the present application are set forth in the following drawings and description to make other features, objects, and advantages of the present application more readily apparent. BRIEF DESCRIPTION OF THE DRAWINGS

[0045] The drawings described herein are used to provide a further understanding of the present application and constitute a part of the present application. The illustrative embodiments of the present application and their descriptions are used to explain the present application and do not constitute an improper limitation on the present application. In the drawings:

[0046] Figure 1 is a flowchart of a method for generating a document based on annotations in an embodiment of the present application;

[0047] Figure 2 This is a diagram showing the effect of the protocol description file in one embodiment of the present application;

[0048] Figure 3 This is a diagram showing the effect of the intermediate code in an embodiment of the present application;

[0049] Figure 4 This is a diagram showing the effect of the API document in one embodiment of the present application;

[0050] Figure 5 This is a diagram showing the effect of the final delivered document in an embodiment of the present application;

[0051] Figure 6 is a structural block diagram of a document generation system based on annotations in an embodiment of the present application;

[0052] Figure 7 It is a structural block diagram of an electronic device in one embodiment of the present application. DETAILED DESCRIPTION

[0053] In order to make the purpose, technical solutions and advantages of the present application clearer, the present application is described and illustrated below in conjunction with the accompanying drawings and embodiments. It should be understood that the specific embodiments described herein are only used to explain the present application and are not intended to limit the present application. Based on the embodiments provided in the present application, all other embodiments obtained by ordinary technicians in the field without making creative work are within the scope of protection of the present application.

[0054] Obviously, the drawings described below are only some examples or embodiments of the present application. For ordinary technicians in this field, the present application can also be applied to other similar scenarios based on these drawings without creative work. In addition, it can also be understood that although the efforts made in this development process may be complicated and lengthy, for ordinary technicians in this field related to the content disclosed in this application, some changes in design, manufacturing or production based on the technical content disclosed in this application are just conventional technical means, and should not be understood as insufficient content disclosed in this application.

[0055] Reference to "embodiments" in this application means that a particular feature, structure, or characteristic described in conjunction with the embodiments may be included in at least one embodiment of the present application. The appearance of the phrase in various locations in the specification does not necessarily refer to the same embodiment, nor is it an independent or alternative embodiment that is mutually exclusive with other embodiments. It is explicitly and implicitly understood by those of ordinary skill in the art that the embodiments described in this application may be combined with other embodiments without conflict.

[0056] Unless otherwise defined, the technical terms or scientific terms involved in this application should be understood by people with ordinary skills in the technical field to which this application belongs. The words "one", "a", "a", "the" and the like involved in this application do not indicate a quantitative limitation, and may represent the singular or plural. The terms "include", "comprise", "have" and any of their variations involved in this application are intended to cover non-exclusive inclusions; for example, a process, method, system, product or device that includes a series of steps or modules (units) is not limited to the listed steps or units, but may also include steps or units that are not listed, or may also include other steps or units inherent to these processes, methods, products or devices. The words "connect", "connected", "coupled" and the like involved in this application are not limited to physical or mechanical connections, but may include electrical connections, whether direct or indirect. The "multiple" involved in this application refers to two or more. "And / or" describes the association relationship of associated objects, indicating that there may be three relationships, for example, "A and / or B" can represent: A exists alone, A and B exist at the same time, and B exists alone. The character " / " generally indicates that the objects before and after are in an "or" relationship. The terms "first", "second", "third", etc. involved in this application are only used to distinguish similar objects and do not represent a specific ordering of the objects.

[0057] API, short for Application Programming Interface, is a set of predefined functions, protocols, and tools for building software applications. API defines how software components communicate with each other, allowing different programs or services to interact without requiring developers to understand or deal with the inner workings of these programs or services.

[0058] In the existing document generation solutions, when go-swagger is used as the API document generation solution, the consistency between business annotations and protocol descriptions must be maintained, which increases the workload of developers. This invention is precisely to solve this problem. This application proposes a solution that allows the back-end to automatically generate reliable API documents by only writing the protocol description normally when developing the API.

[0059] Based on the above situation, the embodiments of the present application provide an annotation-based document generation method, system, electronic device and storage medium.

[0060] In a first aspect, the present application provides a method for generating a document based on annotations. Figure 1 It is a flowchart of the annotation-based document generation method, such as Figure 1 As shown, the document generation solution of the present application is implemented by the following steps.

[0061] Step S1, obtaining a preset custom annotation as a special behavior identifier of the document generator.

[0062] The types of custom annotations in this application include but are not limited to the following: authorization annotations, which are used to define access permissions of the interface; hidden annotations, which are used to define non-public interfaces or fields; verification annotations, which are used to define data constraints for fields; stateless annotations, which are used to define that the API interface does not rely on the status information of previous requests when processing requests; stateful annotations, which are used to define that the API interface relies on the status information of previous requests when processing requests.

[0063] For example, this embodiment first predefines a set of annotation schemes to facilitate adding special behavior identifiers in the document generator. The identifier starts with the character @, which means it is a custom purpose annotation (i.e., custom annotation) rather than an ordinary comment. The following annotations are currently defined:

[0064] Authorization annotation: @RolesAllowed(Admin)

[0065] Hidden annotation: @Hidden

[0066] Validation annotation: @Validate(nonzero,min=1,max=50)

[0067] Stateless Annotation: @Stateless

[0068] Stateful annotation: @Stateful(desc="user id")

[0069] Step S2, using protobuf as the description format, combining the custom annotation to define the data structure of the API interface, and obtaining a protocol description file. The embodiment of the present application defines the protocol description according to the annotation definition, inserts appropriate annotations in appropriate places, and notes that annotations are optional and need to be selected and filled in according to actual needs.

[0070] Specifically, install the Protobuf compiler, create a new proto file through the Protobuf compiler, and define the data structure required by the API interface; in the roto file, use the message keyword to define the message type, and the message type represents the data structure of the API interface; add the custom annotation to the proto file according to the message type to obtain the protocol description file. The protocol description file format of the embodiment of this application is referenced Figure 2 , Figure 2 The comments starting with @ in the gray comments in the protocol description are special-purpose comments, that is, custom comments.

[0071] Step S3, parse the protocol description file, and generate intermediate code that complies with the OpenAPI specification according to the custom annotations in the file. Specifically, obtain a parsing tool, parse the protocol description file with the parsing tool to obtain parsing information; obtain a pre-set code template, render the code template according to the parsing information, and obtain the intermediate code.

[0072] Specifically, this application uses a self-developed parsing tool pbgen, which is used to parse proto files. The proto file format is a public format, and there are many available open source libraries that can parse it. The pbgen used in this application selects the protorefelct library for parsing, and renders it according to the pre-provided template, and finally renders the following code. The template code is as follows:

[0073] func init(){

[0074] / / file:{{.FullyName}}

[0075] pbmeta.Register("{{.FullyName}}",[]string{{{.Leading|trim|quotes|join","}}},[]string{{{.Trailing|trim|quotes|join","}}})

[0076] {{range.Service}}

[0077] / / service:{{.FullyName}}

[0078] pbmeta.Register("{{.FullyName}}",[]string{{{.Leading|trim|quotes|join","}}},[]string{{{.Trailing|trim|quotes|join","}}})

[0079] {{-range.Method}}

[0080] pbmeta.Register("{{.FullyName}}",[]string{{{.Leading|trim|quotes|join","}}},[]string{{{.Trailing|trim|quotes|join","}}})

[0081] {{-end}}

[0082] {{-end}}

[0083] {{-range.EnumType}}

[0084] / / enum:{{.FullyName}}

[0085] pbmeta.Register("{{.FullyName}}",[]string{{{.Leading|trim|quotes|join","}}},[]string{{{.Trailing|trim|quotes|join","}}})

[0086] {{-range.Value}}

[0087] pbmeta.Register("{{.FullyName}}",[]string{{{.Leading|trim|quotes|join","}}},[]string{{{.Trailing|trim|quotes|join","}}})

[0088] {{-end}}

[0089] {{-end}}

[0090] {{range.MessageType}}

[0091] / / message:{{.FullyName}}

[0092] pbmeta.Register("{{.FullyName}}",[]string{{{.Leading|trim|quotes|join","}}},[]string{{{.Trailing|trim|quotes|join","}}})

[0093] {{-range.Field}}

[0094] pbmeta.Register("{{.FullyName}}",[]string{{{.Leading|trim|quotes|join","}}},[]string{{{.Trailing|trim|quotes|join","}}})

[0095] {{-end}}

[0096] {{end}}

[0097] }

[0098] However, this code cannot be run directly. It needs to be loaded by the pbgen tool and the proto file read before the template can be rendered as the final code. Figure 3 .

[0099] Step S4, compile the intermediate code to generate an API document that complies with the OpenAPI specification. In this embodiment, first extract the API definition from the intermediate code, including the data structure of the API request and response; extract the constraints and metadata according to the custom annotations; map the data types in the intermediate code to the data types supported by OpenAPI; that is, generate the parameter definition in the OpenAPI format according to the data structure of the API request and response, as well as the constraints and metadata; assemble the parameter definition and data type in the yaml or json format of the OpenAPI specification to obtain the API document.

[0100] In a specific embodiment, after the intermediate code is generated, it is necessary to parse the intermediate code. In this embodiment, the intermediate code is usually structured and contains information such as API definitions, data types, annotations, etc. Therefore, existing parsing tools can be used to read and parse the intermediate code, such as YAML parsers, Protocol Buffers (protobuf) parsers, etc.

[0101] Specifically, after having the description code generated above, the next step is to assemble the OpenAPI description. The assembly process is as follows: Specifically, process the services defined in each proto file in turn; process the methods or interfaces defined in each service in turn; process the inputs and outputs defined in each method or interface in turn; convert the input and output data structures including annotations into the YAML format specified by OpenAPI; loop through the above process until all service methods are processed; write the converted data document to disk to complete the generation of the OpenAPI description file, recorded as the API document, and display the API document through a visualization tool. The format of the API document is as follows: Figure 4 shown.

[0102] Specifically, first identify the API definition, such as extracting the API definition from the intermediate code, including endpoints, HTTP methods (such as GET, POST, etc.), request and response data structures. Then process the annotations, and extract the constraints and metadata of the fields according to the custom annotations provided by this application (such as @Validate, etc.). These annotations provide additional parameter validation rules and description information. Then map the data type, mapping the data type in the intermediate code to the data type supported by OpenAPI. For example, int32 in protobuf may be mapped to integer type in OpenAPI.

[0103] Then, generate parameter definitions, that is, generate parameter definitions in OpenAPI format according to the data structure of API requests and responses, including request body, query parameters, path parameters, etc. Then apply constraints, that is, apply the constraints defined in the annotation to the corresponding parameter definitions. For example, if a field is marked as @Validate(min=1,max=100), the minimum and maximum attributes of the corresponding field in the OpenAPI document should be set to 1 and 100. Finally, assemble the OpenAPI document, using the YAML or JSON format of the OpenAPI specification to assemble the API document, which includes defining paths, components (such as schemas), info (such as the title and description of the API), etc.

[0104] Preferably, after assembling the API document, you can also write description information, that is, use the description information in the annotation to write clear descriptions for the API endpoints and parameters. These description information will help API users understand how to use the API. Finally, verification and testing are performed. After the conversion is completed, verify whether the generated OpenAPI document accurately reflects the definition of the intermediate code, and perform necessary tests to ensure the correctness of the document. Formatting and optimization can also be performed, such as formatting and optimizing the generated OpenAPI document to ensure the readability and consistency of the document. What's more, OpenAPI tools (such as Swagger Editor) can be used to further edit and verify the document, or these tools can be used directly to visualize and test the API. Save the final OpenAPI document as .yaml or .json files, which can be used by API document generation tools and API gateways.

[0105] Step S5, obtain a preset compilation tool, compile the API document, and obtain the final delivery document. Finally, the tool designed according to the invention compiles the API document into the final document format, and renders it into the final delivery document. Figure 5 shown.

[0106] Figure 5 This is the final result of this embodiment, a final document that can be delivered to users, including the API interface call method, detailed input and output descriptions, whether each field is optional, and input ranges. The description content and constraints of these fields are obtained from the protobuf protocol description, and there is no need to maintain a separate set of descriptions in the business code.

[0107] To summarize, this application simplifies the document description originally located in the business code and migrates it to the protocol description. The document generator does not need to parse the entire business code to generate the document, but only needs to parse the protocol description, which greatly improves the efficiency of the document generator, reduces the workload of developers, and improves the accuracy of the document.

[0108] In another embodiment of the present application, a group of annotations are first defined, including the authorization annotation @RolesAllowed, the hidden annotation @Hidden, the verification annotation @Validate, the stateless annotation @Stateless and the stateful annotation @Stateful. These annotations start with @ and are used to add metadata and constraints in the protobuf protocol description.

[0109] Then use Google protobuf to define the data structure of the API interface for protocol description. The protocol description format uses Google protobuf as the carrier (hereinafter referred to as proto, which is a cross-language description format with a dedicated DSL, commonly used for data serialization, and a widely used serialization open source library on the Internet). Additional information is supplemented through annotation-based annotation syntax so that the code generator can supplement the information that cannot be described in the original proto file when scanning the protocol description file, such as data constraints (for parameter validity verification).

[0110] For example, define a request parameter message type SendRedPacketArgs for sending red envelopes, which includes fields such as red envelope type, resource ID, total amount, number of red envelopes, expiration time, password, related fields, and custom metadata, and use custom annotations to describe the constraints of these fields. The code is as follows:

[0111]

[0112] The above is an interface request parameter for the red envelope service. The purple part is the custom annotation mentioned in this case. By adding annotations to the fields, the code generator can understand the additional descriptive information associated with this field, such as:

[0113]

[0114] This field and its extended annotations contain the following information:

[0115] -Required field (@Validate(nonzero), the legal value range is 1-1000 (min=1, max=1000))

[0116] - int32 type (this is a 32-bit signed number)

[0117] -count field name (used to identify the name of this field program)

[0118] - / / Number of red envelopes

[0119] The document annotation information of the above fields is used to help understand the detailed explanation of the specific meaning of the fields.

[0120] Then, code generation is performed. Specifically, a code generation tool called pbgen is developed, which uses the protoreflect library to parse the protobuf definition file and generates intermediate code based on predefined templates. These templates include registration functions for registering the types and annotation information defined by protobuf into the document generation system.

[0121] Then, OpenAPI description assembly is performed, and the generated intermediate code is used to assemble the API document according to the OpenAPI specification. This includes processing the methods defined in each service, converting the input and output data structures and annotations into YAML format, including the API interface calling method, detailed input and output descriptions, and field constraint information.

[0122] Finally, the document is generated and displayed. The assembled OpenAPI description file is written to disk, and then the API document is displayed using visualization tools such as Swagger Editor or RapiDoc. This allows API users to understand and use the API in a graphical way.

[0123] The detailed operating steps of the embodiment include:

[0124] Step 1: Developers use protobuf to define the data structure and fields of the API interface and add custom annotations.

[0125] Step 2: Use the pbgen tool to scan and parse the protobuf file and generate intermediate code.

[0126] Step 3: Convert the intermediate code into an OpenAPI document.

[0127] Step 4: Use visualization tools to display the OpenAPI document for API users to access and use.

[0128] The embodiment of the present application can generate encoding and decoding classes for data exchange through the compilation tool provided by Google protobuf, and the generated serialization class can be used to realize data conversion. The purpose of this case is to expand the compiler, which can generate various information required to generate API documents (satisfying the OpenAPI specification) while generating encoding and decoding classes, and dynamically construct a protocol description that meets the OpenAPI specification when the document needs to be modified, and use visualization tools to display the OpenAPI description and deliver the API document.

[0129] In summary, compared with the prior art, this application has the following significant technical effects:

[0130] 1. Improve document generation efficiency: This solution simplifies the document description and migrates it to the protocol description. The document generator does not need to scan the full text of the business code, but only needs to scan the protocol description to generate the document, which significantly reduces the time and computing resource consumption of document generation.

[0131] 2. Enhanced document accuracy: Since the document is generated directly from the protocol description, the consistency between the document content and the actual API definition is ensured, errors caused by inconsistencies between business code and document comments are avoided, and the accuracy and reliability of the document are improved.

[0132] 3. Simplify back-end development work: When developers write APIs, they only need to focus on writing protocol descriptions, without the need to maintain additional document comments in the business code, which simplifies back-end development work and reduces the burden on developers.

[0133] 4. Realize automatic document updates: When the API interface or data structure changes, you only need to update the protobuf file, and the document generator can automatically generate the latest document, realizing automatic document updates and reducing the workload of manual document updates.

[0134] 5. Support data constraints and validation: Through custom annotations, this solution can clearly express the data constraints of fields in the document, such as required fields, value ranges, etc., providing clear input guidance for API users.

[0135] 6. Improve API usability: The generated documentation not only includes the interface calling method, but also includes detailed descriptions of input and output and field constraints, so that API users can quickly understand the usage and requirements of the API, improving the API usability.

[0136] 7. Promote standardization of development and maintenance: This solution promotes the standardization of API document generation through unified annotations and automation tools, which helps improve the collaboration efficiency of the development team and the consistency of code maintenance.

[0137] 8. Reduce maintenance costs: Due to the automation and standardization of document generation, the maintenance costs caused by untimely or incorrect document updates are reduced, and the potential risks caused by inconsistencies between documents and codes are also reduced.

[0138] 9. Support for multiple languages ​​and platforms: Due to the cross-language characteristics of Google protobuf, this solution supports the generation of API documents in multiple programming languages ​​and platforms, which improves the versatility and applicability of the solution.

[0139] Through the above technical effects, the present invention not only improves the efficiency and accuracy of API document generation, but also brings convenience to API users and developers, while reducing maintenance costs, and has important practical application value.

[0140] In a second aspect, an embodiment of the present application provides an annotation-based document generation system, which is used to implement the annotation-based document generation method described in any of the above embodiments, including:

[0141] An annotation processor is used to obtain a preset custom annotation as a special behavior identifier of the document generator; and uses protobuf as a description format, and defines the data structure of the API interface in combination with the custom annotation to obtain a protocol description file;

[0142] A code generator, used to parse the protocol description file and generate intermediate code that complies with the OpenAPI specification according to the custom annotations in the file;

[0143] The document renderer is used to compile the intermediate code to generate an API document that complies with the OpenAPI specification; obtain a preset compilation tool, compile the API document, and obtain the final delivery document.

[0144] Specifically, the annotation processor includes:

[0145] Annotation processing module, used to identify and process custom annotations in protocol description files;

[0146] The protocol description generation module is used to create a new proto file through a pre-installed Protobuf compiler and define the data structure required by the API interface; in the roto file, the message keyword is used to define the message type, and the message type represents the data structure of the API interface; according to the message type, corresponding custom annotations are added to the proto file to obtain the protocol description file.

[0147] The document renderer is used to compile the intermediate code, and the process of generating the API document includes:

[0148] Extract API definition from the intermediate code, including the data structure of API request and response; extract constraints and metadata according to the custom annotations; map the data types in the intermediate code to the data types supported by OpenAPI; that is, generate parameter definitions in OpenAPI format according to the data structure of the API request and response, as well as the constraints and metadata; assemble the parameter definitions and data types in the yaml or json format of the OpenAPI specification to obtain the API document.

[0149] In summary, the annotation-based document generation system provided by this application reduces the workload of manual document writing and maintenance by automating the generation process of API documents. At the same time, since the documents are generated directly from the protocol description, the consistency between the documents and the code is ensured, and the accuracy of the documents and the development efficiency are improved.

[0150] It should be noted that the annotation-based document generation system provided in this embodiment is used to implement the above-mentioned implementation mode, and the descriptions that have been made will not be repeated. As used above, the terms "module", "unit", "subunit", etc. can implement a combination of software and / or hardware for a predetermined function. Although the apparatus described in the above embodiments is preferably implemented in software, the implementation of hardware, or a combination of software and hardware, is also possible and conceivable.

[0151] In a third aspect, an embodiment of the present application provides an electronic device, Figure 7 FIG. 1 is a block diagram of an electronic device according to an exemplary embodiment. Figure 7 As shown, the electronic device may include a processor 11 and a memory 12 storing computer program instructions.

[0152] Specifically, the processor 11 may include a central processing unit (CPU), or an application specific integrated circuit (ASIC), or may be configured to implement one or more integrated circuits of the embodiments of the present application.

[0153] Among them, the memory 12 may include a large-capacity memory for data or instructions. By way of example and not limitation, the memory 12 may include a hard disk drive (HDD), a floppy disk drive, a solid-state drive (SSD), a flash memory, an optical disk, a magneto-optical disk, a magnetic tape, or a universal serial bus (USB) drive, or a combination of two or more of these. Where appropriate, the memory 12 may include a removable or non-removable (or fixed) medium. Where appropriate, the memory 12 may be inside or outside a data processing device. In a specific embodiment, the memory 12 is a non-volatile memory. In a specific embodiment, the memory 12 includes a read-only memory (ROM) and a random access memory (RAM). Where appropriate, the ROM may be a mask-programmed ROM, a programmable ROM (Programmable Read-Only Memory, PROM for short), an erasable PROM (Erasable ProgrammableRead-Only Memory, EPROM for short), an electrically erasable PROM (Electrically Erasable ProgrammableRead-Only Memory, EEPROM for short), an electrically alterable ROM (Electrically Alterable Read-Only Memory, EAROM for short) or a flash memory (FLASH) or a combination of two or more of these. Under appropriate circumstances, the RAM can be a static random access memory (SRAM) or a dynamic random access memory (DRAM), wherein the DRAM can be a fast page mode dynamic random access memory (FPMDRAM), an extended data output dynamic random access memory (EDODRAM), a synchronous dynamic random access memory (SDRAM), etc.

[0154] The memory 12 may be used to store or cache various data files that need to be processed and / or used for communication, as well as possible computer program instructions executed by the processor 11 .

[0155] The processor 11 implements any one of the annotation-based document generation methods in the above embodiments by reading and executing computer program instructions stored in the memory 12 .

[0156] In one embodiment, the electronic device may further include a communication interface 13 and a bus 10. Figure 7 As shown, the processor 11, the memory 12, and the communication interface 13 are connected via a bus 10 and communicate with each other.

[0157] The communication interface 13 is used to realize the communication between the modules, devices, units and / or equipment in the embodiment of the present application. The communication port 13 can also realize data communication with other components such as: external devices, image / data acquisition equipment, databases, external storage and image / data processing workstations.

[0158] The bus 10 includes hardware, software or both, and couples the components of the electronic device to each other. The bus 10 includes but is not limited to at least one of the following: a data bus, an address bus, a control bus, an expansion bus, and a local bus. By way of example and not limitation, bus 10 may include an Accelerated Graphics Port (AGP) or other graphics bus, an Extended Industry Standard Architecture (EISA) bus, a Front Side Bus (FSB), a Hyper Transport (HT) interconnect, an Industry Standard Architecture (ISA) bus, an InfiniBand interconnect, a Low Pin Count (LPC) bus, a memory bus, a Micro Channel Architecture (MCA) bus, a Peripheral Component Interconnect (PCI) bus, a PCI-Express (PCI-X) bus, a Serial Advanced Technology Attachment (SATA) bus, a Video Electronics Standards Association Local Bus (VLB) bus, or other suitable buses or a combination of two or more of these. Where appropriate, bus 10 may include one or more buses. Although embodiments of the present application describe and illustrate a particular bus, the present application contemplates any suitable bus or interconnect.

[0159] In a fourth aspect, an embodiment of the present application provides a computer-readable storage medium having a program stored thereon, and when the program is executed by a processor, the annotation-based document generation method provided in the first aspect is implemented.

[0160] The readable storage medium may include but is not limited to: a portable disk, a hard disk, a random access memory, a read-only memory, an erasable programmable read-only memory, an optical storage device, a magnetic storage device or any suitable combination of the above.

[0161] In a possible implementation, the present invention can also be implemented in the form of a program product, which includes program code. When the program product runs on a terminal device, the program code is used to enable the terminal device to execute the steps of the annotation-based document generation method provided in the first aspect.

[0162] The program code for executing the present invention may be written in any combination of one or more programming languages, and may be executed entirely on a user device, partially on a user device, as an independent software package, partially on a user device and partially on a remote device, or entirely on a remote device.

[0163] The technical features of the above-described embodiments may be arbitrarily combined. To make the description concise, not all possible combinations of the technical features in the above-described embodiments are described. However, as long as there is no contradiction in the combination of these technical features, they should be considered to be within the scope of this specification.

[0164] The above-mentioned embodiments only express several implementation methods of the present application, and the descriptions thereof are relatively specific and detailed, but they cannot be understood as limiting the scope of the invention patent. It should be pointed out that, for a person of ordinary skill in the art, several variations and improvements can be made without departing from the concept of the present application, and these all belong to the protection scope of the present application. Therefore, the protection scope of the patent of the present application shall be subject to the attached claims.

Claims

1. A document generation method based on annotation, characterized in that: include: Get the preset custom annotation as a special behavior identifier of the document generator; Using protobuf as the description format, combining the custom annotations to define the data structure of the API interface, and obtaining a protocol description file; Parse the protocol description file, and generate intermediate code that complies with the OpenAPI specification according to the custom annotations in the protocol description file; Compile the intermediate code to generate API documentation; Obtain a preset compilation tool, compile the API document, and obtain a final delivery document.

2. The method according to claim 1, characterized in that The types of custom annotations include: Authorization annotations, used to define access rights to the interface; Hidden annotations are used to define non-public interfaces or fields; Verification annotations are used to define data constraints for fields; Stateless annotation, used to define that the API interface does not rely on the state information of previous requests when processing requests; Stateful annotations are used to define that the API interface depends on the state information of previous requests when processing requests.

3. The method according to claim 1, characterized in that: The data structure of the API interface is defined according to the custom annotation to obtain a protocol description file, including: Identify and process custom annotations in protocol description files; Create a new proto file through the pre-installed Protobuf compiler and define the data structure required by the API interface; In the roto file, the message keyword is used to define the message type, and the message type represents the data structure of the API interface; According to the message type, corresponding custom annotations are added to the proto file to obtain the protocol description file.

4. The method according to claim 1, characterized in that: The parsing of the protocol description file and generating intermediate code that complies with the OpenAPI specification according to the custom annotations in the file include: Obtain a parsing tool, and parse the protocol description file using the parsing tool to obtain parsing information; A preset code template is obtained, and the code template is rendered according to the parsing information to obtain the intermediate code.

5. The method according to claim 4, characterized in that The step of compiling the intermediate code to generate an API document that complies with the OpenAPI specification includes: Extracting an API definition from the intermediate code, including data structures of API requests and responses; Extracting constraints and metadata based on the custom annotations; Map the data types in the intermediate code to the data types supported by OpenAPI; That is, generating a parameter definition in the OpenAPI format according to the data structure of the API request and response, as well as the constraints and metadata; The parameter definition and data type are assembled in the yaml or json format of the OpenAPI specification to obtain the API document.

6. A document generation system based on annotations, characterized in that: The method for generating a document based on annotations according to any one of claims 1 to 5 comprises: An annotation processor is used to obtain a preset custom annotation as a special behavior identifier of the document generator; and uses protobuf as a description format, and defines the data structure of the API interface in combination with the custom annotation to obtain a protocol description file; A code generator, used to parse the protocol description file and generate intermediate code that complies with the OpenAPI specification according to the custom annotations in the protocol description file; The document renderer is used to compile the intermediate code to generate API documents; and obtain a preset compilation tool to compile the API documents to obtain the final delivery document.

7. The system according to claim 6, characterized in that The annotation processor includes: Annotation processing module, used to identify and process custom annotations in protocol description files; The protocol description generation module is used to create a new proto file through a pre-installed Protobuf compiler and define the data structure required by the API interface; in the roto file, the message keyword is used to define the message type, and the message type represents the data structure of the API interface; according to the message type, corresponding custom annotations are added to the proto file to obtain the protocol description file.

8. The system according to claim 6, characterized in that The document renderer is used to compile the intermediate code, and the process of generating the API document includes: Extract API definition from the intermediate code, including the data structure of API request and response; extract constraints and metadata according to the custom annotations; map the data types in the intermediate code to the data types supported by OpenAPI; that is, generate parameter definitions in OpenAPI format according to the data structure of the API request and response, as well as the constraints and metadata; assemble the parameter definitions and data types in the yaml or json format of the OpenAPI specification to obtain the API document.

9. An electronic device, characterized in that: The invention comprises a memory, a processor, and a computer program stored in the memory and executable on the processor, wherein the processor implements the annotation-based document generation method according to any one of claims 1 to 5 when executing the computer program.

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

Images