JAX-RS interface document generation method and device, equipment and medium

Abstract

The embodiment of the invention discloses a JAX-RS interface document generation method and device, equipment and a medium, and the method comprises the steps: activating a corresponding code logic through a submission hook when a specified Java file is submitted to a Git warehouse; the specified Java file is scanned through the code logic, so that a controller class with a JAX-RS mark is recognized; parsing the grammar of the specified Java file through the code logic so as to find each available JAX-RS HTTP (Hyper Text Transport Protocol) endpoint; checking whether each controller class or each available JAX-RS HTTP (Hyper Text Transport Protocol) endpoint lacks a Swagger annotation or not through the code logic; if it is detected that the specified controller class or the specified available JAX-RS HTTP endpoint lacks the Swagger annotation, the corresponding annotation is automatically inserted, and a modified Java file is obtained; and submitting the modified Java file to the Git warehouse, and triggering a Maven compiling process of a multi-module project through a specified automatic server to obtain a JAX-RS interface document.

Description

Technical Field

[0001] The present invention relates to the field of computer technology, and in particular to a method, device, equipment and medium for generating a JAX-RS interface document. Background Art

[0002] Common JAX-RS interface document generation tools include Swagger Core, Swagger-jaxrs2, SpringFox, OpenAPI Tools, MicroProfile OpenAPI, Enunciate, Swagger Maven Plugin, Swagger Gradle Plugin, RESTEasy Swagger, and Jersey Swagger. These tools generally support automatic scanning of JAX-RS annotations, can generate JSON or YAML documents that comply with the OpenAPI specification, and provide customization and extension capabilities. Most tools can be integrated into the build process, and some also provide UI components for visualizing API documents.

[0003] These tools all rely on developers to correctly mark JAX-RS controller classes and interfaces with Swagger annotations. However, in the actual development process, due to various reasons such as changes in requirements and version updates, Swagger annotations are often ignored or fail to correctly and accurately describe the actual controller code behavior, which damages the readability and accuracy of the OpenAPI document and reduces the document's usability. Summary of the invention

[0004] One or more embodiments of the present specification provide a JAX-RS interface document generation method, apparatus, device, and medium, which are used to solve the technical problems raised by the background technology.

[0005] One or more embodiments of this specification adopt the following technical solutions:

[0006] One or more embodiments of this specification provide a JAX-RS interface document generation method, the method comprising:

[0007] When submitting a specified Java file to the Git repository, the corresponding code logic is activated through the submission hook;

[0008] Scanning the specified Java file through the code logic to identify the controller class with the JAX-RS tag;

[0009] Parsing the syntax of the specified Java file through the code logic to find each available JAX-RS HTTP endpoint;

[0010] Check through the code logic whether each controller class or each available JAX-RS HTTP endpoint lacks a Swagger annotation;

[0011] If it is found that the specified controller class or the specified available JAX-RS HTTP endpoint lacks Swagger annotations, the corresponding annotations will be automatically inserted to obtain the modified Java file;

[0012] The modified Java file is submitted to the Git repository, and the Maven compilation process of the multi-module project is triggered by a designated automation server to obtain a JAX-RS interface document.

[0013] It should be noted that the embodiments of this specification have the following beneficial effects through the above contents:

[0014] Automatic detection and repair: By activating code logic when committing to the Git repository, you can automatically detect whether JAX-RS controller classes and HTTP endpoints are missing Swagger annotations, which reduces the need for manual inspection and improves development efficiency.

[0015] Instant feedback: When developers submit code, missing Swagger annotations can be checked and fixed immediately, which can provide immediate feedback to developers, avoiding the accumulation of problems in the code base and thus improving code quality.

[0016] Code consistency: Automatic insertion of Swagger annotations ensures that each controller class and HTTP endpoint has complete annotation information, which helps keep the API documentation accurate and consistent.

[0017] Reduced Human Errors: Automated processing reduces the potential for errors that can occur due to manual work, lowering the risk of inaccurate documentation due to omitted or incorrectly applied annotations.

[0018] Improve development process efficiency: By integrating into the Git repository and Maven build process, developers can see document updates more quickly, thus speeding up the development process.

[0019] Furthermore, the Swagger annotation includes input parameters, return values, and request descriptions of the operation, as well as descriptions of related controllers.

[0020] It should be noted that the embodiments of this specification have the following beneficial effects through the above contents:

[0021] Regarding the input parameters of the operation, the parameter information of each API operation is provided, which can include the parameter type, name, location (path, query, request body, etc.), whether it is required, and possible default values, which can help developers quickly understand how to use the API. Providing clear documentation makes it easier for third-party developers or users to build applications that interact with the API.

[0022] Regarding the return value of the operation, describe the data type, structure, and possible response code returned by the API operation. Ensure that developers understand the content and format of the API response. Help users perform correct error handling and data processing based on the data returned by the API.

[0023] Request instructions for operations provide detailed instructions on request methods (such as GET, POST, PUT, DELETE, etc.), including the purpose of the request, possible impact, and side effects. Help users understand the behavior of the API and the expected results. Avoid incorrect usage due to misunderstanding of request behavior.

[0024] Description of the relevant controllers, describing the role and responsibilities of the controller class and how to organize related API operations. Help developers understand the overall structure and design intent of the API. Provide contextual information about the controller class and its operations to help better maintain and expand the API.

[0025] Furthermore, the Maven compilation process of the multi-module project is triggered by specifying an automation server to obtain a JAX-RS interface document, including:

[0026] Use the Swagger Maven Plugin to scan the Swagger annotations of each module and output an OpenAPI document for each module. Each OpenAPI document contains a separate list of HTTP endpoints and the models referenced by each OpenAPI document.

[0027] Trigger the own Maven Plugin code logic to merge the OpenAPI documents to obtain the JAX-RS interface document.

[0028] It should be noted that the embodiments of this specification have the following beneficial effects through the above contents:

[0029] Automated document generation: The automated server can automatically trigger the document generation process without manual intervention, reducing human errors and repetitive work.

[0030] Unified standards: Use the Swagger Maven Plugin to ensure that the documentation of all modules follows the OpenAPI specification, thereby ensuring the consistency and standardization of the documentation.

[0031] Modular documentation: Generating a separate OpenAPI document for each module helps maintain and update the documentation of each module, and also facilitates document consultation for a specific module.

[0032] Integrated build process: Integrate document generation into the Maven build process so that document generation is performed in parallel with project compilation, testing and other steps, improving the efficiency of the build process.

[0033] Fast feedback: Automatically generating documentation during the compilation process can quickly provide developers with documentation updates, helping to identify and fix problems in a timely manner.

[0034] Furthermore, the triggering of the own Maven Plugin code logic merges the OpenAPI documents to obtain the JAX-RS interface document, including:

[0035] Trigger the own Maven Plugin code logic to uniformly replace the Swagger definition of each module with global information. The Swagger definition includes the name, contact person, and version of each module.

[0036] Trigger the own Maven Plugin code logic to merge the models corresponding to each module, and globally unify the names of the models used by each module;

[0037] Trigger the own Maven Plugin code logic to sort the OpenAPI documents of each module according to the preset rules to obtain the JAX-RS interface document.

[0038] It should be noted that the embodiments of this specification have the following beneficial effects through the above contents:

[0039] Unified Swagger definition replacement: By replacing the Swagger definition of each module with global information, such as module name, contact person, and version, the consistency and standardization of all API documents can be ensured, which is very useful for maintaining and updating API documents. The unification of global information means that when updating documents, only one modification is required to apply to all modules, reducing duplication of work and improving the efficiency of document maintenance. When users consult API documents, they can quickly identify documents of different modules because each module has clear identification information.

[0040] Global unification of models: By merging the models corresponding to each module and using a globally unified model name, data redundancy can be reduced and the representation of the API model can be simplified. Globally unified model names and definitions help ensure data consistency between different modules and reduce potential errors caused by inconsistent models. Developers can more easily understand and use shared models because the model structure is unified, which helps speed up development.

[0041] Sorting of OpenAPI documents: Sorting OpenAPI documents according to preset rules can make JAX-RS interface documents more orderly, improve the readability of the documents, and make it easier for developers to find the information they need. Sorted documents make it easier for developers to quickly locate specific interfaces by keywords, improving search efficiency and user experience. In the automated deployment process, sorted documents can be deployed and synchronized more efficiently, reducing errors and delays in the deployment process.

[0042] Furthermore, the method further comprises:

[0043] In the OpenAPI document, the description information of all pre-set HTTP endpoints is obtained, and the corresponding interfaces are hidden according to the description information.

[0044] It should be noted that the embodiments of this specification have the following beneficial effects through the above contents:

[0045] Enhanced security: By hiding certain interfaces, you can prevent sensitive information from being leaked when it should not be made public, such as internal API endpoints or interfaces with sensitive data. Hiding unnecessary interfaces can reduce the potential attack surface of the application and reduce the risk of being exploited by malicious users.

[0046] Improve user experience: Exposing all interface details can make API documentation complex and difficult to understand. Hiding interfaces that do not need to be exposed can simplify the documentation and make key information more prominent. Users can focus on interfaces related to their work without having to search for irrelevant information in complex documents.

[0047] Furthermore, the method further comprises:

[0048] Add additional descriptive information to the OpenAPI document, where the additional descriptive information includes one or more of version description, interface usage, and security information.

[0049] It should be noted that the embodiments of this specification have the following beneficial effects through the above contents:

[0050] Enhanced documentation completeness: By adding additional descriptive information, OpenAPI documentation is more comprehensive and provides more contextual information about the API.

[0051] Improve comprehensibility: Providing version notes helps users understand the current status and historical changes of the API, thereby improving the comprehensibility of the documentation.

[0052] Convenient version management: Version notes help developers and administrators track API version updates for easier management and maintenance.

[0053] Clarify purpose: The description of the purpose of the interface helps users quickly understand the function and purpose of each API, reducing unnecessary incorrect use.

[0054] Improved security awareness: The addition of security information increases users’ awareness of potential API security risks and helps them take appropriate security measures.

[0055] Furthermore, the Maven compilation process of the multi-module project is triggered by specifying an automation server to obtain a JAX-RS interface document, including:

[0056] Trigger the Maven compilation process of the multi-module project by specifying an automation server to obtain the OpenAPI document in JSON format;

[0057] The OpenAPI document in JSON format is rendered by a PDF generation tool to obtain a JAX-RS interface document.

[0058] It should be noted that the embodiments of this specification have the following beneficial effects through the above contents:

[0059] Automatic document generation: The automation server can trigger Maven compilation on a scheduled or on-demand basis to automatically generate JAX-RS interface documentation, reducing manual intervention.

[0060] Improve efficiency: Automated processes reduce the time required to manually generate documents, improving development efficiency and the speed of document updates.

[0061] Consistency guarantee: Automatically generating documents ensures that each generated document is based on the latest code status, reducing errors that may be introduced by manual updates.

[0062] Real-time documentation updates: As the project is compiled, the documentation is automatically updated, ensuring that developers can view the latest status of the API in real time.

[0063] One or more embodiments of this specification provide a JAX-RS interface document generation device, including:

[0064] The code activation unit activates the corresponding code logic through the commit hook when submitting a specified Java file to the Git repository;

[0065] A controller identification unit, scanning the specified Java file through the code logic to identify a controller class with a JAX-RS tag;

[0066] An available endpoint search unit, which parses the syntax of the specified Java file through the code logic to find each available JAX-RS HTTP endpoint;

[0067] An annotation checking unit checks, through the code logic, whether each controller class or each available JAX-RSHTTP endpoint lacks a Swagger annotation;

[0068] The file modification unit, if it is detected that the specified controller class or the specified available JAX-RS HTTP endpoint lacks Swagger annotations, will automatically insert the corresponding annotations to obtain the modified Java file;

[0069] The document generation unit submits the modified Java file to the Git repository, triggers the Maven compilation process of the multi-module project through a designated automation server, and obtains a JAX-RS interface document.

[0070] One or more embodiments of this specification provide a JAX-RS interface document generation device, including:

[0071] at least one processor; and,

[0072] a memory communicatively connected to the at least one processor; wherein,

[0073] The memory stores instructions executable by the at least one processor, the instructions being executed by the at least one processor to enable the at least one processor to:

[0074] When submitting a specified Java file to the Git repository, the corresponding code logic is activated through the submission hook;

[0075] Scanning the specified Java file through the code logic to identify the controller class with the JAX-RS tag;

[0076] Parsing the syntax of the specified Java file through the code logic to find each available JAX-RS HTTP endpoint;

[0077] Check through the code logic whether each controller class or each available JAX-RS HTTP endpoint lacks a Swagger annotation;

[0078] If it is found that the specified controller class or the specified available JAX-RS HTTP endpoint lacks Swagger annotations, the corresponding annotations will be automatically inserted to obtain the modified Java file;

[0079] The modified Java file is submitted to the Git repository, and the Maven compilation process of the multi-module project is triggered by a designated automation server to obtain a JAX-RS interface document.

[0080] One or more embodiments of this specification provide a non-volatile computer storage medium storing computer executable instructions, which can achieve the following when executed by a computer:

[0081] When submitting a specified Java file to the Git repository, the corresponding code logic is activated through the submission hook;

[0082] Scanning the specified Java file through the code logic to identify the controller class with the JAX-RS tag;

[0083] Parsing the syntax of the specified Java file through the code logic to find each available JAX-RS HTTP endpoint;

[0084] Check through the code logic whether each controller class or each available JAX-RS HTTP endpoint lacks a Swagger annotation;

[0085] If it is found that the specified controller class or the specified available JAX-RS HTTP endpoint lacks Swagger annotations, the corresponding annotations will be automatically inserted to obtain the modified Java file;

[0086] The modified Java file is submitted to the Git repository, and the Maven compilation process of the multi-module project is triggered by a designated automation server to obtain a JAX-RS interface document.

[0087] At least one of the above technical solutions adopted in the embodiments of this specification can achieve the following beneficial effects:

[0088] Automatic detection and repair: By activating code logic when committing to the Git repository, you can automatically detect whether JAX-RS controller classes and HTTP endpoints are missing Swagger annotations, which reduces the need for manual inspection and improves development efficiency.

[0089] Instant feedback: When developers submit code, missing Swagger annotations can be checked and fixed immediately, which can provide immediate feedback to developers, avoiding the accumulation of problems in the code base and thus improving code quality.

[0090] Code consistency: Automatic insertion of Swagger annotations ensures that each controller class and HTTP endpoint has complete annotation information, which helps keep the API documentation accurate and consistent.

[0091] Reduced Human Errors: Automated processing reduces the potential for errors that can occur due to manual work, lowering the risk of inaccurate documentation due to omitted or incorrectly applied annotations.

[0092] Improve development process efficiency: By integrating into the Git repository and Maven build process, developers can see document updates more quickly, thus speeding up the development process. BRIEF DESCRIPTION OF THE DRAWINGS

[0093] In order to more clearly illustrate the technical solutions in the embodiments of this specification or the prior art, the following briefly introduces the drawings required for use in the embodiments or the prior art description. Obviously, the drawings described below are only some embodiments recorded in this specification. For ordinary technicians in this field, other drawings can be obtained based on these drawings without creative labor. In the drawings:

[0094] Figure 1 A flowchart of a JAX-RS interface document generation method provided for one or more embodiments of this specification;

[0095] Figure 2 A schematic diagram of a JAX-RS interface document automatic generation method flow chart provided for one or more embodiments of this specification;

[0096] Figure 3 A schematic diagram of the structure of a JAX-RS interface document generation device provided for one or more embodiments of this specification;

[0097] Figure 4 A schematic diagram of the structure of a JAX-RS interface document generation device provided for one or more embodiments of this specification. DETAILED DESCRIPTION

[0098] The embodiments of this specification provide a JAX-RS interface document generation method, apparatus, device and medium.

[0099] JAX-RS is part of JavaEE and provides a set of standardized annotations and interfaces for developing RESTful Web services. JAX-RS makes extensive use of Java annotations to define Web resources and HTTP methods. Specifically, Web resources are represented by ordinary Java classes, which are modified with JAX-RS annotations. Common annotations include: @Path: specifies the URL path of the resource, @GET, @POST, @PUT, @DELETE, etc.: specifies the HTTP method; @Produces: specifies the MIME type of the response; @Consumes: specifies the MIME type of the request; @PathParam, @QueryParam, @HeaderParam: used for parameter extraction.

[0100] The OpenAPI specification (formerly the Swagger specification) is a standardized format for describing RESTful APIs. It allows developers to define the structure of an API in a machine-readable and human-readable way, including: available endpoints and operations (GET / users, POST / users, etc.), operation parameters, authentication methods, contact information, licenses, terms of use, and other information. OpenAPI documents can be written in JSON or YAML format, providing a basis for API documentation, client SDK generation, and server stub generation. There are many open source OpenAPI document viewing tools that enable developers and operations personnel to interact interactively between web pages and API endpoints, understand interface behavior, and explore interface capabilities.

[0101] The controller classes and methods of the JAX-RS standard contain rich type information about the HTTP interface, but there are still deficiencies in generating rich and readable OpenAPI documents. For example, although the input parameter type structure information is available, it lacks whether the input parameter type is required and the meaning of the field; for example, although the interface path information is available, it lacks descriptions of the interface usage and restrictions. Therefore, in actual production, Swagger annotations are often used to enrich the controller classes and methods of the JAX-RS standard. For example, the @Api annotation is usually used at the class level to describe the entire API controller or resource class, and can provide information such as the overall description, label, and basic path of the API. The @ApiOperation annotation is used at the method level to describe a specific API operation or endpoint, including the description of the operation, HTTP method, response type, and possible response code. @PathParam is used to mark method parameters, indicating that the parameter is extracted from the URL path. The @ApiParam annotation is used to describe the parameters of the API operation, and can specify the name, description, and whether the parameter is required. The @ApiResponse and @ApiResponses annotations are used to describe possible responses of the API, including response codes, descriptions, and returned data models. The @ApiModel and @ApiModelProperty annotations are used to describe data models and their properties, typically for complex request or response objects.

[0102] It is a common requirement to add Swagger annotations to JAX-RS standard controller classes and methods and automatically generate OpenAPI documents. This process usually involves: parsing JAX-RS annotations, extracting API metadata, mapping the extracted information to the structure of the OpenAPI specification, and generating JSON or YAML documents that conform to the OpenAPI format. It is mainly used to ensure that the API documentation is synchronized with the actual implementation. Correct API interface documentation is crucial for functional accuracy, consistency maintenance, development efficiency, tool integration, version control, standardization, and cross-language and platform support.

[0103] Common Swagger document scanning and generation tools include Swagger Core, Swagger-jaxrs2, SpringFox, OpenAPI Tools, MicroProfile OpenAPI, Enunciate, Swagger Maven Plugin, Swagger Gradle Plugin, RESTEasy Swagger, and Jersey Swagger. These tools generally support automatic scanning of JAX-RS annotations, can generate JSON or YAML documents that comply with the OpenAPI specification, and provide customization and extension capabilities. Most tools can be integrated into the build process, and some also provide UI components for visualizing API documents.

[0104] These tools all rely on developers to correctly mark JAX-RS controller classes and interfaces with Swagger annotations. However, in the actual development process, due to various reasons such as changes in requirements and version updates, Swagger annotations are often ignored or fail to correctly and accurately describe the actual controller code behavior, which damages the readability and accuracy of the OpenAPI document and reduces the document's usability.

[0105] For open source tools such as Swagger Maven Plugin, although they can be well integrated with the Maven build process, they do not support multi-module OpenAPI documents well. They can only generate separate OpenAPI documents for each module, which is not friendly to the management and use of documents in multi-module projects, such as OpenDayLight controllers. Finally, most of these open source tools can only generate OpenAPI documents (JSON or YAML format), but cannot be output as PDF documents. They need to rely on online web tools such as Swagger Doc to view them, which is not friendly to the interface viewing needs in many offline scenarios.

[0106] To address these shortcomings, the present invention aims to use Git commit hooks to trigger automatic checking of submitted files, parse Java syntax, perform missing checks and completions for various Swagger annotations on controller classes and methods, and automatically filter, check and merge OpenAPI documents scanned and generated by Swagger Maven Plugin during the Maven build process, hide internal API endpoints, and output them as a well-annotated complete OpenAPI document, and finally export them as PDF documents for users to use offline.

[0107] In order to enable those skilled in the art to better understand the technical solutions in this specification, the technical solutions in the embodiments of this specification will be clearly and completely described below in conjunction with the drawings in the embodiments of this specification. Obviously, the described embodiments are only part of the embodiments of this specification, not all of the embodiments. Based on the embodiments of this specification, all other embodiments obtained by ordinary technicians in this field without creative work should fall within the scope of protection of this specification.

[0108] Figure 1 A schematic diagram of a JAX-RS interface document generation method provided in one or more embodiments of this specification, which can be executed by a JAX-RS interface document generation system. Certain input parameters or intermediate results in the process allow manual intervention and adjustment to help improve accuracy.

[0109] The method steps of the embodiment of this specification are as follows:

[0110] S101, when submitting a specified Java file to the Git repository, activating the corresponding code logic through the submission hook.

[0111] In Example S101 of this specification, the following specific implementation scheme can be adopted:

[0112] Determine the code logic that needs to be triggered: Determine the tasks that need to be performed when a specific Java file is submitted, such as compiling, testing, formatting code, generating API documentation, etc.

[0113] Write code logic: Write corresponding Java code or scripts according to the tasks to be performed.

[0114] Configure Git repository: Set up a pre-commit hook in a local or remote Git repository.

[0115] Write a hook script: Create a hook script file (e.g. pre-commit) which will be run before each commit.

[0116] Set the hook script execution permission: Make sure the hook script has execution permission.

[0117] Write the hook script content: In the hook script, write logic to detect whether the specified Java file has been modified and call the corresponding code logic.

[0118] S102: Scan the specified Java file through the code logic to identify the controller class with the JAX-RS tag.

[0119] In Example S102 of this specification, the following specific implementation scheme can be adopted:

[0120] Determine JAX-RS tags: You need to clarify which annotations or tags represent a controller class. In Java, annotations such as @Path, @GET, @POST, @PUT, @DELETE are usually used to mark RESTful controller classes.

[0121] Identify target Java files: Identify the list of Java files that need to be scanned, which may be stored in the local file system or in a version control system.

[0122] Use text search tools: Use text search tools or regular expressions to scan annotations in Java files.

[0123] S103: parsing the syntax of the specified Java file through the code logic to find each available JAX-RS HTTP endpoint.

[0124] In Example S103 of this specification, the following specific implementation scheme can be adopted:

[0125] Choose a Java parser: Choose a Java code parser, such as JavaParser, Apache CommonsLang, or Eclipse Java Compiler. These tools can help analyze the grammatical structure of Java source code.

[0126] Get Java source files: Make sure you have the path to the specified Java files. These files may be stored in the local file system, in a version control system, or in an IDE.

[0127] Parse Java File: Parse the Java file using the selected parser. Here are the general steps:

[0128] If using JavaParser:

[0129] Create a JavaFile object to represent the Java source file. Use the JavaParser API to traverse the AST (Abstract Syntax Tree) and find JAX-RS related annotations and endpoints.

[0130] If using Apache Commons Lang:

[0131] Use the org.apache.commons.lang3.StringUtils class to help parse the string. Read the Java file content and then use regular expressions to match JAX-RS annotations.

[0132] If using Eclipse Java Compiler:

[0133] Use the classes in the org.eclipse.jdt.core package to create compiler workspaces and compilation units. Analyze the compilation unit to get the AST.

[0134] Identify JAX-RS HTTP endpoints: Look for the following JAX-RS annotations in the AST returned by the parser:

[0135] ˋ@Pathˋ: Marks the path of the resource class or method.

[0136] ˋ@GETˋ, ˋ@POSTˋ, ˋ@PUTˋ, ˋ@DELETEˋ: mark the HTTP method.

[0137] ˋ@Producesˋ, ˋ@Consumesˋ: mark the supported media types.

[0138] ˋ@QueryParamˋ, ˋ@PathParamˋ, ˋ@HeaderParamˋ: mark request parameters.

[0139] Collect endpoint information: For each JAX-RS endpoint found, collect the following information:

[0140] The fully qualified name of the endpoint class. The signature of the endpoint method. The requested HTTP method. The requested path template. The supported media types.

[0141] S104, checking, through the code logic, whether each controller class or each available JAX-RS HTTP endpoint lacks a Swagger annotation.

[0142] In Example S104 of this specification, the Swagger annotation may include input parameters, return values, and request descriptions of the operation, as well as descriptions of related controllers, which may be implemented through the following specific implementation schemes:

[0143] Define Swagger annotations: Determine which Swagger annotations are required, including:

[0144] ˋ@Apiˋ: used in controller classes to provide basic information about the API.

[0145] ˋ@ApiOperationˋ: Used for methods, provides a description of the operation.

[0146] ˋ@ApiParamˋ: used for method parameters, providing a description of the parameters.

[0147] ˋ@ApiResponseˋ: Used for methods to provide a description of the response.

[0148] ˋ@ApiResponsesˋ: For methods, provides a set of possible responses.

[0149] ˋ@ApiVersionˋ: Used in controller classes to provide the API version.

[0150] Get JAX-RS endpoint information: As mentioned earlier, parse the Java source file using a Java parser to find all JAX-RS HTTP endpoints.

[0151] Check Swagger annotations: For each JAX-RS endpoint, the following checks are performed:

[0152] For controller classes: Check whether the @Api annotation is used and whether the necessary information is provided (such as value, produces, tags, etc.). Check whether the @ApiVersion annotation is used and whether the version information is provided.

[0153] For endpoint methods: Check if the @ApiOperation annotation is used and if a description of the operation is provided. Check if the @ApiParam annotation is used and if a description is provided for each parameter. Check if the @ApiResponse or @ApiResponses annotation is used and if a description is provided for each response.

[0154] Record missing annotations: If you find that Swagger annotations are missing, record the following information:

[0155] The name of the missing Swagger annotation. The name of the controller class or endpoint method where the annotation is missing. Required additional information, such as expected annotation parameters.

[0156] It should be noted that the embodiments of this specification have the following beneficial effects through the above contents:

[0157] Regarding the input parameters of the operation, the parameter information of each API operation is provided, which can include the parameter type, name, location (path, query, request body, etc.), whether it is required, and possible default values, which can help developers quickly understand how to use the API. Providing clear documentation makes it easier for third-party developers or users to build applications that interact with the API.

[0158] Regarding the return value of the operation, describe the data type, structure, and possible response code returned by the API operation. Ensure that developers understand the content and format of the API response. Help users perform correct error handling and data processing based on the data returned by the API.

[0159] Request instructions for operations provide detailed instructions on request methods (such as GET, POST, PUT, DELETE, etc.), including the purpose of the request, possible impact, and side effects. Help users understand the behavior of the API and the expected results. Avoid incorrect usage due to misunderstanding of request behavior.

[0160] Description of the relevant controllers, describing the role and responsibilities of the controller class and how to organize related API operations. Help developers understand the overall structure and design intent of the API. Provide contextual information about the controller class and its operations to help better maintain and expand the API.

[0161] S105, if it is detected that the specified controller class or the specified available JAX-RS HTTP endpoint lacks Swagger annotations, the corresponding annotations are automatically inserted to obtain a modified Java file.

[0162] In Example S105 of this specification, the following specific implementation scheme can be adopted:

[0163] Define Swagger annotation templates: Create template strings for Swagger annotations, which will be dynamically populated with parameters based on the context.

[0164] Parse Java files: Use the code parsing library to load and parse the specified Java file and generate an abstract syntax tree (AST).

[0165] Identify JAX-RS endpoints and methods: Traverse the AST and identify all JAX-RS endpoint classes and methods, which are usually annotated with @Path, @GET, @POST, @PUT, @DELETE, etc.

[0166] Check for Swagger annotations: For each identified JAX-RS endpoint and method, check for missing Swagger annotations.

[0167] Automatically insert Swagger annotations: If Swagger annotations are missing, insert the corresponding annotations according to the defined template.

[0168] For controller classes, check and insert the @Api annotation.

[0169] For methods, check and insert annotations such as @ApiOperation, @ApiParam, @ApiResponse, etc.

[0170] Save the modified file: The modified AST is converted back to a Java source code string. Save this string back to the original Java file, or save it to a new file.

[0171] S106, submitting the modified Java file to the Git repository, triggering the Maven compilation process of the multi-module project by specifying an automation server, and obtaining a JAX-RS interface document.

[0172] In Example S106 of this specification, for a multi-module project, each module calls the Swagger MavenPlugin plug-in to generate a module-specific Swagger definition file. These files are independent of each other, and each file contains an independent HTTP endpoint list and the model it references, which is not convenient for unified reading and management of project documents. Therefore, in actual production, it is usually necessary to merge the Swagger definition files of these modules.

[0173] There are some problems with the merger. First, the Swagger definition of each module contains meta information such as name, contact person, version, etc., which need to be replaced with global information. Second, each module contains the models it uses, which are crucial to explaining how the HTTP endpoint is called. The model names of each module may conflict, so it is necessary to use a unified model name and modify the models referenced by all module HTTP endpoints so that they can maintain the correct correspondence. In addition, there are differences in importance and affinity between modules, so certain principles must be followed when sorting documents, such as putting documents of modules with similar functions together and putting important modules in front.

[0174] The above analysis shows the matters that need to be paid attention to when merging module Swagger definition files. The present invention provides some code logic to automatically call the code execution module Swagger merging process at the end of the Jenkins compilation phase, and call the PDF rendering tool to render, output and archive the unified project Swagger document.

[0175] It should be noted that, for the above content, the embodiments of this specification provide further analysis content, as shown below:

[0176] In the embodiments of this specification, the Swagger Maven Plugin can be used to scan the Swagger annotations of each module and output an OpenAPI document for each module. Each OpenAPI document contains an independent HTTP endpoint list and the model referenced by each OpenAPI document; the own Maven Plugin code logic is triggered to merge the OpenAPI documents to obtain a JAX-RS interface document.

[0177] It should be noted that the above content can be implemented through the following specific implementation plans:

[0178] Configure Swagger Maven Plugin: You can add the configuration of SwaggerMaven Plugin in the pom.xml file of all modules.

[0179] Generate OpenAPI documentation: Execute the following Maven command in the root directory of the project to generate OpenAPI documentation for all modules.

[0180] Create a custom Maven Plugin: Create a custom Maven Plugin to merge the OpenAPI documents of all modules. The following are the basic steps to create a custom Plugin:

[0181] Define the Plugin's Mojo:

[0182] Create a Java class that inherits from org.apache.maven.plugin.AbstractMojo and define the goals and configuration of the plugin.

[0183] Implement merging logic: Implement merging logic in the Mojo class, read the OpenAPI documents of all modules, and then merge them into one document.

[0184] Configure output: Define the configuration of the plugin output, such as the output directory.

[0185] Register Mojo: Use the @Mojo annotation on the Plugin's Mojo class to define the execution goals and configuration parameters of the plugin.

[0186] Configure custom Plugin: Add custom Plugin configuration in pom.xml in the root directory of the project.

[0187] Merge OpenAPI documents: Execute the specified Maven command to trigger the custom Plugin and merge the OpenAPI documents.

[0188] It should be noted that the embodiments of this specification have the following beneficial effects through the above contents:

[0189] Automated document generation: The automated server can automatically trigger the document generation process without manual intervention, reducing human errors and repetitive work.

[0190] Unified standards: Use the Swagger Maven Plugin to ensure that the documentation of all modules follows the OpenAPI specification, thereby ensuring the consistency and standardization of the documentation.

[0191] Modular documentation: Generating a separate OpenAPI document for each module helps maintain and update the documentation of each module, and also facilitates document consultation for a specific module.

[0192] Integrated build process: Integrate document generation into the Maven build process so that document generation is performed in parallel with project compilation, testing and other steps, improving the efficiency of the build process.

[0193] Fast feedback: Automatically generating documentation during the compilation process can quickly provide developers with documentation updates, helping to identify and fix problems in a timely manner.

[0194] Furthermore, when the own Maven Plugin code logic is triggered to merge the OpenAPI documents to obtain the JAX-RS interface document, the own Maven Plugin code logic can be triggered to uniformly replace the Swagger definition of each module with global information, and the Swagger definition includes the name, contact person and version of each module; the own Maven Plugin code logic is triggered to merge the models corresponding to each module, and the name of the model used by each module is globally unified; the own Maven Plugin code logic is triggered to sort the OpenAPI documents of each module according to preset rules to obtain the JAX-RS interface document.

[0195] It should be noted that the embodiments of this specification have the following beneficial effects through the above contents:

[0196] Unified Swagger definition replacement: By replacing the Swagger definition of each module with global information, such as module name, contact person, and version, the consistency and standardization of all API documents can be ensured, which is very useful for maintaining and updating API documents. The unification of global information means that when updating documents, only one modification is required to apply to all modules, reducing duplication of work and improving the efficiency of document maintenance. When users consult API documents, they can quickly identify documents of different modules because each module has clear identification information.

[0197] Global unification of models: By merging the models corresponding to each module and using a globally unified model name, data redundancy can be reduced and the representation of the API model can be simplified. Globally unified model names and definitions help ensure data consistency between different modules and reduce potential errors caused by inconsistent models. Developers can more easily understand and use shared models because the model structure is unified, which helps speed up development.

[0198] Sorting of OpenAPI documents: Sorting OpenAPI documents according to preset rules can make JAX-RS interface documents more orderly, improve the readability of the documents, and make it easier for developers to find the information they need. Sorted documents make it easier for developers to quickly locate specific interfaces by keywords, improving search efficiency and user experience. In the automated deployment process, sorted documents can be deployed and synchronized more efficiently, reducing errors and delays in the deployment process.

[0199] Furthermore, the Swagger document provides descriptions of all HTTP endpoints, but a considerable number of interfaces are limited to internal use for security or other purposes. Therefore, it is necessary to distinguish these interfaces into those that can be exposed and those that need to be hidden according to certain strategies, and then shield the HTTP endpoints that need to be hidden, and only display the public, exposed parts.

[0200] In view of the above considerations, the embodiments of the present specification can obtain the description information of all pre-set HTTP endpoints (equivalent to the above-mentioned certain policies) in the OpenAPI document, and hide the corresponding interfaces according to the description information.

[0201] It should be noted that the embodiments of this specification have the following beneficial effects through the above contents:

[0202] Enhanced security: By hiding certain interfaces, you can prevent sensitive information from being leaked when it should not be made public, such as internal API endpoints or interfaces with sensitive data. Hiding unnecessary interfaces can reduce the potential attack surface of the application and reduce the risk of being exploited by malicious users.

[0203] Improve user experience: Exposing all interface details can make API documentation complex and difficult to understand. Hiding interfaces that do not need to be exposed can simplify the documentation and make key information more prominent. Users can focus on interfaces related to their work without having to search for irrelevant information in complex documents.

[0204] Furthermore, the method also includes: adding additional descriptive information to the OpenAPI document, wherein the additional descriptive information includes one or more of version description, interface usage and security information.

[0205] It should be noted that the embodiments of this specification have the following beneficial effects through the above contents:

[0206] Enhanced documentation completeness: By adding additional descriptive information, OpenAPI documentation is more comprehensive and provides more contextual information about the API.

[0207] Improve comprehensibility: Providing version notes helps users understand the current status and historical changes of the API, thereby improving the comprehensibility of the documentation.

[0208] Convenient version management: Version notes help developers and administrators track API version updates for easier management and maintenance.

[0209] Clarify purpose: The description of the purpose of the interface helps users quickly understand the function and purpose of each API, reducing unnecessary incorrect use.

[0210] Improved security awareness: The addition of security information increases users’ awareness of potential API security risks and helps them take appropriate security measures.

[0211] Furthermore, when the Maven compilation process of the multi-module project is triggered by the specified automation server to obtain the JAX-RS interface document, the Maven compilation process of the multi-module project can be triggered by the specified automation server to obtain the OpenAPI document in JSON format; the OpenAPI document in JSON format is rendered by a PDF generation tool to obtain the JAX-RS interface document.

[0212] It should be noted that the embodiments of this specification have the following beneficial effects through the above contents:

[0213] Automatic document generation: The automation server can trigger Maven compilation on a scheduled or on-demand basis to automatically generate JAX-RS interface documentation, reducing manual intervention.

[0214] Improve efficiency: Automated processes reduce the time required to manually generate documents, improving development efficiency and the speed of document updates.

[0215] Consistency guarantee: Automatically generating documents ensures that each generated document is based on the latest code status, reducing errors that may be introduced by manual updates.

[0216] Real-time documentation updates: As the project is compiled, the documentation is automatically updated, ensuring that developers can view the latest status of the API in real time.

[0217] It should be noted that the embodiment of this specification starts working from the Git commit hook trigger of the project code, executes the code logic to find the controller class with JAX-RS markup that is submitted for modification, and then parses the syntax of this Java file and finds each available JAX-RS HTTP endpoint. If the controller or endpoint lacks the Swagger annotation tag, these annotations are inserted to provide OpenAPI input parameters, return values, and request instructions for the operation, instructions for the controller group, etc. Git submission can be rejected according to different configurations. After that, the modified Java file is replaced, and the submitter can supplement and improve the annotation information provided by default, and finally submit the code to the warehouse.

[0218] The code submitted to the repository triggers the CI / CD process. Taking Jenkins as an example, it triggers the Maven compilation process of multi-module projects. During this process, the Swagger Maven Plugin is used to scan the annotations of each module and output the OpenAPI document for each module. Finally, the Maven Plugin code logic is triggered to merge these scattered OpenAPI documents. This process includes merging the definition models for each module, replacing the old model for each module, hiding the internal HTTP endpoints according to the additional comment information, adding other additional description information, and outputting it as an integrated OpenAPI JSON format document. Finally, this document is rendered and exported through a PDF generation tool to build the document of the final real-time reaction code JAX-RS interface. The above process is as follows Figure 2 The following is a flow chart of the JAX-RS interface document automatic generation method. In the figure, Git commits the code, then commits the inspection tool, Java syntax parsing, JAX-RS annotation inspection, Swagger annotation completion (which can be understood through ChatGPT code logic), further completion by the developer, CI / CD Maven compilation, document filtering tool, document model merging, document definition replacement, document merging, and finally, PDF rendering.

[0219] It should be noted that the present invention provides a fully automated JAX-RS interface document generation method. The action is executed when Git is submitted and triggered when the CI / CD process is compiled, and a readable PDF document is finally obtained. No manual intervention is required throughout the process. No more coordination resources are required for multi-team collaborative projects. The cost of communication and collaboration can be effectively reduced, and the inconsistency between documents and software interface behaviors can be reduced. It can meet the needs of software interfaces to hide internal endpoints, merge and convert, and meet the needs of software interfaces for offline use, etc.

[0220] In addition, the present invention provides a simple and automated method for providing automatic interface document output for old JAX-RS interface projects. The code script will scan the project to find all JAX-RS controller classes, then understand the code intent, add Swagger annotations to it and trigger compilation to generate OpenAPI documents for each module, and finally perform merging and output a single PDF document.

[0221] Figure 3 A structural diagram of a JAX-RS interface document generation device provided for one or more embodiments of this specification includes: a code activation unit 301, a controller identification unit 302, an available endpoint search unit 303, an annotation checking unit 304, a file modification unit 305 and a document generation unit 306.

[0222] The code activation unit 301 activates the corresponding code logic through the submission hook when submitting a specified Java file to the Git repository;

[0223] A controller identification unit 302 scans the specified Java file through the code logic to identify the controller class with the JAX-RS tag;

[0224] An available endpoint search unit 303 parses the syntax of the specified Java file through the code logic to find each available JAX-RS HTTP endpoint;

[0225] An annotation checking unit 304 checks, through the code logic, whether each controller class or each available JAX-RSHTTP endpoint lacks a Swagger annotation;

[0226] The file modification unit 305 automatically inserts the corresponding annotation to obtain a modified Java file if it is detected that the specified controller class or the specified available JAX-RS HTTP endpoint lacks the Swagger annotation;

[0227] The document generation unit 306 submits the modified Java file to the Git repository, triggers the Maven compilation process of the multi-module project through a designated automation server, and obtains a JAX-RS interface document.

[0228] Figure 4 A schematic diagram of a JAX-RS interface document generation device provided for one or more embodiments of this specification includes:

[0229] at least one processor; and,

[0230] a memory communicatively connected to the at least one processor; wherein,

[0231] The memory stores instructions executable by the at least one processor, the instructions being executed by the at least one processor to enable the at least one processor to:

[0232] When submitting a specified Java file to the Git repository, the corresponding code logic is activated through the submission hook;

[0233] Scanning the specified Java file through the code logic to identify the controller class with the JAX-RS tag;

[0234] Parsing the syntax of the specified Java file through the code logic to find each available JAX-RS HTTP endpoint;

[0235] Check through the code logic whether each controller class or each available JAX-RS HTTP endpoint lacks a Swagger annotation;

[0236] If it is found that the specified controller class or the specified available JAX-RS HTTP endpoint lacks Swagger annotations, the corresponding annotations will be automatically inserted to obtain the modified Java file;

[0237] The modified Java file is submitted to the Git repository, and the Maven compilation process of the multi-module project is triggered by a designated automation server to obtain a JAX-RS interface document.

[0238] One or more embodiments of this specification provide a non-volatile computer storage medium storing computer executable instructions, which can achieve the following when executed by a computer:

[0239] When submitting a specified Java file to the Git repository, the corresponding code logic is activated through the submission hook;

[0240] Scanning the specified Java file through the code logic to identify the controller class with the JAX-RS tag;

[0241] Parsing the syntax of the specified Java file through the code logic to find each available JAX-RS HTTP endpoint;

[0242] Check through the code logic whether each controller class or each available JAX-RS HTTP endpoint lacks a Swagger annotation;

[0243] If it is found that the specified controller class or the specified available JAX-RS HTTP endpoint lacks Swagger annotations, the corresponding annotations will be automatically inserted to obtain the modified Java file;

[0244] The modified Java file is submitted to the Git repository, and the Maven compilation process of the multi-module project is triggered by a designated automation server to obtain a JAX-RS interface document.

[0245] Each embodiment in this specification is described in a progressive manner, and the same or similar parts between the embodiments can be referred to each other, and each embodiment focuses on the differences from other embodiments. In particular, for the device, equipment, and non-volatile computer storage medium embodiments, since they are basically similar to the method embodiments, the description is relatively simple, and the relevant parts can be referred to the partial description of the method embodiment.

Claims

1. A JAX-RS interface document generation method, characterized in that: include: When submitting a specified Java file to the Git repository, the corresponding code logic is activated through the submission hook; Scanning the specified Java file through the code logic to identify the controller class with the JAX-RS tag; Parsing the syntax of the specified Java file through the code logic to find each available JAX-RS HTTP endpoint; Check through the code logic whether each controller class or each available JAX-RS HTTP endpoint lacks a Swagger annotation; If it is found that the specified controller class or the specified available JAX-RS HTTP endpoint lacks Swagger annotations, the corresponding annotations will be automatically inserted to obtain the modified Java file; The modified Java file is submitted to the Git repository, and the Maven compilation process of the multi-module project is triggered by a designated automation server to obtain a JAX-RS interface document.

2. The method according to claim 1, characterized in that The Swagger annotations include input parameters, return values, and request descriptions of the operation, as well as descriptions of related controllers.

3. The method according to claim 1, characterized in that The Maven compilation process of the multi-module project is triggered by specifying an automation server to obtain a JAX-RS interface document, including: Use the Swagger Maven Plugin to scan the Swagger annotations of each module and output an OpenAPI document for each module. Each OpenAPI document contains a separate list of HTTP endpoints and the models referenced by each OpenAPI document. Trigger the own Maven Plugin code logic to merge the OpenAPI documents to obtain the JAX-RS interface document.

4. The method according to claim 3, characterized in that The triggering of the own Maven Plugin code logic merges the OpenAPI documents to obtain the JAX-RS interface document, including: Trigger the own Maven Plugin code logic to uniformly replace the Swagger definition of each module with global information. The Swagger definition includes the name, contact person, and version of each module. Trigger the own Maven Plugin code logic to merge the models corresponding to each module, and globally unify the names of the models used by each module; Trigger the own Maven Plugin code logic to sort the OpenAPI documents of each module according to the preset rules to obtain the JAX-RS interface document.

5. The method according to claim 4, characterized in that The method further comprises: In the OpenAPI document, the description information of all pre-set HTTP endpoints is obtained, and the corresponding interfaces are hidden according to the description information.

6. The method according to claim 4, characterized in that The method further comprises: Add additional descriptive information to the OpenAPI document, where the additional descriptive information includes one or more of version description, interface usage, and security information.

7. The method according to claim 1, characterized in that The Maven compilation process of the multi-module project is triggered by specifying an automation server to obtain a JAX-RS interface document, including: Trigger the Maven compilation process of the multi-module project by specifying an automation server to obtain the OpenAPI document in JSON format; The OpenAPI document in JSON format is rendered by a PDF generation tool to obtain a JAX-RS interface document.

8. A JAX-RS interface document generation device, characterized in that: include: The code activation unit activates the corresponding code logic through the commit hook when submitting a specified Java file to the Git repository; A controller identification unit, scanning the specified Java file through the code logic to identify a controller class with a JAX-RS tag; An available endpoint search unit, which parses the syntax of the specified Java file through the code logic to find each available JAX-RS HTTP endpoint; An annotation checking unit checks, through the code logic, whether each controller class or each available JAX-RS HTTP endpoint lacks a Swagger annotation; The file modification unit, if it is detected that the specified controller class or the specified available JAX-RS HTTP endpoint lacks Swagger annotations, will automatically insert the corresponding annotations to obtain the modified Java file; The document generation unit submits the modified Java file to the Git repository, triggers the Maven compilation process of the multi-module project through a designated automation server, and obtains a JAX-RS interface document.

9. A JAX-RS interface document generation device, characterized in that: include: at least one processor; as well as, a memory communicatively connected to the at least one processor; wherein, The memory stores instructions executable by the at least one processor, the instructions being executed by the at least one processor to enable the at least one processor to: When submitting a specified Java file to the Git repository, the corresponding code logic is activated through the submission hook; Scanning the specified Java file through the code logic to identify the controller class with the JAX-RS tag; Parsing the syntax of the specified Java file through the code logic to find each available JAX-RS HTTP endpoint; Check through the code logic whether each controller class or each available JAX-RS HTTP endpoint lacks a Swagger annotation; If it is found that the specified controller class or the specified available JAX-RS HTTP endpoint lacks Swagger annotations, the corresponding annotations will be automatically inserted to obtain the modified Java file; The modified Java file is submitted to the Git repository, and the Maven compilation process of the multi-module project is triggered by a designated automation server to obtain a JAX-RS interface document.

10. A non-volatile computer storage medium, characterized in that: Computer executable instructions are stored, and when the computer executable instructions are executed by a computer, the following can be achieved: When submitting a specified Java file to the Git repository, the corresponding code logic is activated through the submission hook; Scanning the specified Java file through the code logic to identify the controller class with the JAX-RS tag; Parsing the syntax of the specified Java file through the code logic to find each available JAX-RS HTTP endpoint; Check through the code logic whether each controller class or each available JAX-RS HTTP endpoint lacks a Swagger annotation; If it is found that the specified controller class or the specified available JAX-RS HTTP endpoint lacks Swagger annotations, the corresponding annotations will be automatically inserted to obtain the modified Java file; The modified Java file is submitted to the Git repository, and the Maven compilation process of the multi-module project is triggered by a designated automation server to obtain a JAX-RS interface document.

Images