CN119621133A

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

Info

Publication number: CN119621133A
Application number: CN202411705852.0A
Authority: CN
Inventors: 马章竞
Original assignee: Inspur Network Technology Shandong Co ltd
Current assignee: Inspur Network Technology Shandong Co ltd
Priority date: 2024-11-26
Filing date: 2024-11-26
Publication date: 2025-03-14

Abstract

The embodiments of the present specification disclose a JAX-RS interface document generation method, apparatus, device and medium, including: when submitting a specified Java file to a Git repository, activating corresponding code logic through a submission hook; scanning the specified Java file through the code logic to identify a controller class with a JAX-RS tag; parsing the syntax of the specified Java file through the code logic to find each available JAX-RS HTTP endpoint; checking 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 a Swagger annotation, automatically inserting the corresponding annotation to obtain a modified Java file; submitting the modified Java file to the Git repository, triggering the Maven compilation process of the multi-module project through a specified automation server, and obtaining a JAX-RS interface document.

Description

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

Technical Field

The present disclosure relates to the field of computer technologies, and in particular, to a method, an apparatus, a device, and a medium for generating a JAX-RS interface document.

Background

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, et al. These tools generally support automatic scanning of JAX-RS annotations, are capable of generating JSON or YAML documents that conform to the OpenAPI specification, and provide custom and expansion capabilities. Most tools can be integrated into the build process, some also provide UI components for visualizing API documents.

These tools all rely on the correct JAX-RS controller class and interface mark Swagger annotation of a developer, but in the actual development process, the Swagger annotation is often ignored or cannot describe the actual controller code behavior correctly and accurately due to various reasons such as requirement change, version update and the like, so that the readability and accuracy of the OpenAPI document are damaged, and the use value of the document is reduced.

Disclosure of Invention

One or more embodiments of the present disclosure provide a method, an apparatus, a device, and a medium for generating a JAX-RS interface document, which are used to solve the technical problems set forth in the background art.

One or more embodiments of the present disclosure adopt the following technical solutions:

One or more embodiments of the present specification provide a JAX-RS interface document generation method, including:

when a specified Java file is submitted to the Git warehouse, corresponding code logic is activated through a submission hook;

Scanning the specified Java file through the code logic to identify a controller class with a JAX-RS mark;

parsing, by the code logic, the syntax of the specified Java file to find each available JAX-RS HTTP endpoint;

Checking by said code logic whether the or each available JAX-RS HTTP endpoint lacks Swagger annotations;

If the defect of Swagger annotation of the specified controller class or the specified available JAX-RS HTTP endpoint is detected, automatically inserting the corresponding annotation to obtain a modified Java file;

and submitting the modified Java file to the Git warehouse, and triggering a Maven compiling process of the multi-module item through an appointed automation server to obtain a JAX-RS interface document.

It should be noted that, through the above, the embodiment of the present disclosure has the following beneficial effects:

Automated detection and repair by activating code logic at the time of Git repository commit, it is possible to automatically detect if JAX-RS controller classes and HTTP endpoints lack Swagger annotations, which reduces the need for manual inspection, improving development efficiency.

And the immediate feedback is that the deletion of the Swagger annotation is checked and repaired immediately when the developer submits the code, and the immediate feedback can be carried out to the developer, so that the problem accumulated in a code library is avoided, and the code quality is improved.

Code consistency-automatically inserting Swagger notes ensures that each controller class and HTTP endpoint has complete annotation information, which helps to maintain the accuracy and consistency of the API document.

The manual errors are reduced, the automatic processing reduces errors possibly caused by manual operation, and the risk of inaccurate documents caused by ignoring or misapplying notes is reduced.

The development flow efficiency is improved, and a developer can see the document update faster by integrating the development flow efficiency into the Git warehouse and the Maven construction process, so that the development flow is quickened.

Further, the Swagger annotation includes an entry, return value and request description for the operation, and a description for the associated controller.

Regarding the participation of the operations, providing parameter information for each API operation, which may include parameter type, name, location (path, query, request body, etc.), whether necessary and possible default values, may help the developer quickly understand how the API is used. Providing a clear document enables third party developers or users to more easily build applications that interact with the API.

With respect to the return value of the operation, the type of data, structure, and possible response code returned by the API operation are described. Ensuring that the developer knows the content and format of the API response. And helping the user to perform correct error processing and data processing according to the data returned by the API.

A detailed description of the method of the request (e.g., GET, POST, PUT, DELETE, etc.) is provided with respect to the requested description of the operation, including the purpose of the request, possible effects and side effects. Helping the user understand the behavior and expected results of the API. Misuse due to misunderstanding of the request behavior is avoided.

With respect to the description of the relevant controllers, the role, responsibilities, and how the relevant API operations are organized are described. Helping the developer to understand the overall structure and design intent of the API. Providing contextual information about the controller class and its operation helps to better maintain and extend the API.

Further, triggering a Maven compiling process of the multi-module item by the specified automation server to obtain a JAX-RS interface document, including:

Scanning Swagger notes of each module by using SWAGGER MAVEN Plugin, and outputting OpenAPI documents for each module, wherein each OpenAPI document comprises an independent HTTP endpoint list and a model referenced by each OpenAPI document;

and triggering own Maven plug in code logic to combine the OpenAPI documents to obtain the JAX-RS interface document.

And the automatic document generation, namely the automatic server can automatically trigger the document generation process without manual intervention, so that the manual error and the repeated work are reduced.

Unified standard-use SWAGGER MAVEN Plugin to ensure that all module documents follow the OpenAPI specification, thereby ensuring the consistency and standardization of the documents.

And generating a separate OpenAPI document for each module, so that the documents of each module are maintained and updated, and document reference for a specific module is facilitated.

Integrating the generation of the document into the Maven construction process, so that the generation of the document and the steps of compiling, testing and the like of the project are executed in parallel, and the efficiency of the construction process is improved.

And the quick feedback is that the document is automatically generated in the compiling process, so that the document update can be quickly provided for a developer, and the problem can be found out in time and repaired.

Further, the triggering of the own Maven plug in code logic to merge the OpenAPI documents to obtain a JAX-RS interface document includes:

Triggering own Maven plug code logic to uniformly replace Swagger definition of each module with global information, wherein the Swagger definition comprises a name, a contact person and a version of each module;

triggering own Maven plug code logic to merge the models corresponding to each module, and globally unifying the names of the models used by each module;

And triggering own Maven plug in code logic to sequence the OpenAPI documents of each module according to preset rules so as to obtain JAX-RS interface documents.

Unified Swagger definition replacement by uniformly replacing the Swagger definition of each module with global information such as module name, contacts and version, consistency and standardization of all API documents can be ensured, which is very useful for maintaining and updating API documents. The unification of the global information enables that when the document is updated, the method can be applied to all modules only by modifying one place, reduces repeated labor and improves the efficiency of document maintenance. The user can quickly identify documents of different modules when referring to the API document because each module has explicit identification information.

And the global unification of the models, namely, the data redundancy can be reduced and the representation of the API model can be simplified by merging the models corresponding to each module and using the globally unified model name. The globally unified model names and definitions help to ensure data consistency among different modules and reduce potential errors caused by model inconsistency. The developer can more easily understand and use the shared model because the model structure is unified, which helps to accelerate development speed.

Sequencing of the OpenAPI documents, namely sequencing the OpenAPI documents according to preset rules, so that the JAX-RS interface documents are more orderly, the readability of the documents is improved, and a developer can find required information more easily. The sorted documents are convenient for developers to quickly locate a specific interface through keywords, so that the searching efficiency and the user experience are improved. In an automated deployment process, the ordered documents can be deployed and synchronized more efficiently, reducing errors and delays in the deployment process.

Further, the method further comprises:

And acquiring preset description information of all HTTP endpoints in the OpenAPI document, and hiding corresponding interfaces according to the description information.

Enhanced security by hiding certain interfaces, sensitive information can be prevented from leaking without being exposed, such as internal API endpoints or interfaces with sensitive data. Hiding unnecessary interfaces can reduce the potential attack surface of the application program and reduce the risk of being utilized by malicious users.

Improving the user experience-disclosing detailed information of all interfaces may complicate and make difficult the understanding of API documents. Hiding the interface that does not require disclosure can simplify the document so that the critical information is more prominent. The user can concentrate on the interfaces related to his work without having to search for irrelevant information in a complex document.

Further, the method further comprises:

additional description information is added to the OpenAPI document, wherein the additional description information comprises one or more of version description, interface use and security information.

the integrity of the document is enhanced by adding additional descriptive information, the OpenAPI document is more comprehensive, providing more contextual information about the API.

Providing a version specification helps the user to understand the current state and history changes of the API, thereby improving the understandability of the document.

Version description is helpful for developers and administrators to track version update of the API, and is convenient for management and maintenance.

Explicit use-description of interface use helps the user to quickly understand the function and goal of each API, reducing unnecessary misuse.

The safety awareness is improved, namely the safety information is added to improve the awareness of the user on the potential safety risk of the API, and corresponding safety measures are facilitated to be adopted.

triggering a Maven compiling process of the multi-module item through a specified automation server to obtain an OpenAPI document in a JSON format;

rendering the JSON-format OpenAPI document through a PDF generating tool to obtain a JAX-RS interface document.

Automated document generation, wherein an automated server can trigger Maven compiling at regular time or according to needs, so that JAX-RS interface documents are automatically generated, and manual intervention is reduced.

The efficiency is improved, the time required for manually generating the document is reduced by the automatic process, and the development efficiency and the document updating speed are improved.

The consistency ensures that the automatically generated documents ensure that each generated document is based on the latest code state, and errors possibly caused by manual updating are reduced.

And updating the real-time document, namely automatically updating the document along with compiling the project, so that a developer can check the latest state of the API in real time.

One or more embodiments of the present specification provide a JAX-RS interface document generating apparatus, including:

The code activating unit activates corresponding code logic through a submitting hook when submitting a specified Java file to the Git warehouse;

a controller identification unit for scanning the specified Java file through the code logic to identify a controller class with a JAX-RS mark;

An available endpoint lookup unit that parses syntax of the specified Java file through the code logic to find each available JAX-RS HTTP endpoint;

an annotation checking unit for checking, by said code logic, whether each controller class or each of said available JAX-RS HTTP endpoints lacks Swagger annotations;

The file modification unit is used for automatically inserting corresponding notes if the defect of the Swagger notes of the specified controller class or the specified available JAX-RS HTTP endpoint is detected, so as to obtain a modified Java file;

and the document generation unit submits the modified Java file to the Git warehouse, and triggers a Maven compiling process of the multi-module item through a specified automation server to obtain a JAX-RS interface document.

One or more embodiments of the present specification provide a JAX-RS interface document generating apparatus including:

at least one processor, and

A memory communicatively coupled to the at least one processor, wherein,

The memory stores instructions executable by the at least one processor, the instructions are executable by the at least one processor to enable the at least one processor to:

One or more embodiments of the present description provide a non-volatile computer storage medium storing computer-executable instructions that, when executed by a computer, enable:

The above-mentioned at least one technical scheme that this description embodiment adopted can reach following beneficial effect:

Drawings

In order to more clearly illustrate the embodiments of the present description or the technical solutions in the prior art, the drawings that are required in the embodiments or the description of the prior art will be briefly described below, it being obvious that the drawings in the following description are only some of the embodiments described in the present description, and that other drawings may be obtained according to these drawings without inventive effort for a person skilled in the art. In the drawings:

FIG. 1 is a flow diagram of a method for generating a JAX-RS interface document according to one or more embodiments of the present disclosure;

FIG. 2 is a schematic flow diagram of a method for automatically generating a JAX-RS interface document according to one or more embodiments of the present disclosure;

FIG. 3 is a schematic diagram of a JAX-RS interface document generating apparatus according to one or more embodiments of the present disclosure;

FIG. 4 is a schematic diagram of a structure of a JAX-RS interface document generating device according to one or more embodiments of the present disclosure.

Detailed Description

The embodiment of the specification provides a method, a device, equipment and a medium for generating a JAX-RS interface document.

JAX-RS is part of JavaEE and provides a standardized set of annotations and interfaces for developing RESTful Web services. JAX-RS uses Java annotations to define Web resources and HTTP methods in large numbers, and specifically, web resources are represented by generic Java classes that are modified using JAX-RS annotations, commonly used annotations are @ Path @ URL Path for specified resources @ GET @ POST @ PUT @ DELETE etc.: specify HTTP methods @ Produces @ specify MIME types for responses @ Consumes @ specify MIME types for requests @ PATHPARAM @ QueryParam, @ HEADERPARAM @ for parameter extraction.

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

The controller class and the method of the JAX-RS standard comprise abundant type information about HTTP interfaces, but the generation of abundant and readable OpenAPI documents has the defects that whether the input type is necessary or not and the field meaning is described in spite of the input type structure information, such as interface path information but description about interface purposes, limits and the like, so in actual production, the controller class and the method of the JAX-RS standard are enriched through Swagger annotation, such as @ Api annotation is commonly used for class level and used for describing the whole API controller or resource class, and the general description, the labels, the basic path and the like of the API can be provided. The @ ApiOperation note is for a method level, describing a particular API operation or endpoint, including description of the operation, HTTP method, type of response and possible response code, etc. The @ PATHPARAM is used to mark the method parameter, indicating that the parameter is extracted from the URL path. The @ ApiParam notes the parameters used to describe the operation of the API, and may specify the name, description, whether it is necessary, etc. of the parameters. The @ ApiResponse and @ ApiResponses notes are used to describe the API's possible responses, including response code, description, and returned data model. The @ ApiModel and @ ApiModelProperty notes are used to describe the data model and its attributes, typically for complex request or response objects.

Adding Swagger annotations to the controller classes and methods of the JAX-RS standard and automatically generating OpenAPI documents is a common requirement, and this process typically involves parsing the JAX-RS annotations, extracting API metadata, mapping the extracted information to the structure of the OpenAPI specification, generating JSON or YAML documents that conform to the OpenAPI format. The method is mainly used for ensuring that the API document keeps synchronous with the actual implementation, and the correct API interface document is very important for functional accuracy, consistency maintenance, development efficiency, tool integration, version control, standardization and cross-language and platform support.

Common Swagger document scan generation tools include Swagger Core、Swagger-jaxrs2、SpringFox、OpenAPI Tools、MicroProfile OpenAPI、Enunciate、Swagger Maven Plugin、Swagger Gradle Plugin、RESTEasy Swagger and Jersey Swagger et al. These tools generally support automatic scanning of JAX-RS annotations, are capable of generating JSON or YAML documents that conform to the OpenAPI specification, and provide custom and expansion capabilities. Most tools can be integrated into the build process, some also provide UI components for visualizing API documents.

For the SWAGGER MAVEN plug in or other open source tools, although the open source tools can be well integrated with the Maven construction process, the open api document support for multiple modules is not good, and only a separate open api document can be generated for each module, which is not friendly for the management and use of documents in multiple module projects, such as OpenDayLight controllers and other scenes. Finally, most of these open source tools can only generate OpenAPI documents (JSON or YAML format), but cannot output PDF documents, and need to rely on Web online tools such as Swagger Doc for viewing, which is not friendly to the requirements of interface review in many offline scenarios.

Aiming at the defects, the invention aims to trigger automatic checking of a submitted file by using a Git submitting hook, analyze Java grammar, perform deletion checking and complementation for various Swagger notes on controller classes and methods, automatically filter, check and merge SWAGGER MAVEN Plugin scanning and generated OpenAPI documents in a Maven construction process, hide internal API endpoints, output a well-marked complete OpenAPI document, and finally export the complete OpenAPI document as a PDF document for offline use by a user.

In order to make the technical solutions in the present specification better understood by those skilled in the art, the technical solutions in the embodiments of the present specification will be clearly and completely described below with reference to the drawings in the embodiments of the present specification, and it is obvious that the described embodiments are only some embodiments of the present specification, not all embodiments. All other embodiments, which can be made by one of ordinary skill in the art based on the embodiments herein without making any inventive effort, shall fall within the scope of the present disclosure.

FIG. 1 is a flow diagram of a method for generating a JAX-RS interface document that may be performed by a JAX-RS interface document generating system according to one or more embodiments of the present disclosure. Some input parameters or intermediate results in the flow allow for manual intervention adjustments to help improve accuracy.

The method flow steps of the embodiment of the present specification are as follows:

S101, when a specified Java file is submitted to the Git warehouse, corresponding code logic is activated through a submission hook.

In the example S101 of the present specification, the following specific embodiments may be adopted:

Code logic that needs to be triggered is determined, tasks that need to be performed when submitting a particular Java file, such as compiling, testing, formatting code, generating API documents, etc.

And writing code logic, namely writing corresponding Java codes or scripts according to tasks required to be executed.

Configuring the Git repository, setting a commit hook (pre-commit hook) in the local or remote Git repository.

Writing a hook script creates a hook script file (e.g., pre-commit) that will run before each commit.

And setting the execution authority of the hook script, namely ensuring that the hook script has the execution authority.

And writing the content of the hook script, namely writing logic in the hook script to detect whether a specified Java file is modified and calling corresponding code logic.

S102, scanning the specified Java file through the code logic to identify the controller class with the JAX-RS mark.

In example S102 of the present specification, the following specific embodiments may be adopted:

It is determined which annotations or tags represent a controller class that should be made clear. In Java, the RESTful controller class is typically marked with annotations of @ Path, @ GET, @ POST, @ PUT, @ DELETE, and the like.

Determining the target Java files, determining the list of Java files that need to be scanned, which may be stored in the local file system or version control system.

A text search tool is used that scans the annotations in the Java file with the text search tool or regular expression.

S103, analyzing the grammar of the specified Java file through the code logic so as to find each available JAX-RS HTTP endpoint.

In example S103 of the present specification, the following specific embodiments may be adopted:

Selecting a Java parser, selecting a Java code parser such as JavaParser, apache Commons Lang, or Eclipse Java Compiler. These tools can help analyze the syntax structure of Java source code.

Obtaining Java source files, namely ensuring that a path of a specified Java file exists. These files may be stored in a local file system, version control system, or in an IDE.

Parsing the Java file using the selected parser. The following general procedure is as follows:

if JavaParser is used:

a 'JavaFile' object is created to represent the Java source file. The API of 'JavaParser' is used to traverse AST (abstract syntax tree) for JAX-RS related annotations and endpoints.

If Apache Commons Lang is used:

The 'org.apache.common.lang3.StringUtils' class is used to help parse strings. The Java file content is read and then JAX-RS annotations are matched using regular expressions.

If Eclipse Java Compiler is used:

the compiler workspace and compilation unit are created using classes in the 'org.eclipse.jdt.core' package. The compiling unit is analyzed to obtain the AST.

Identifying a JAX-RS HTTP endpoint by looking up the following JAX-RS annotations in the AST returned by the parser:

Marking the Path of a resource class or method.

The HTTP method is marked by the's @ GET's, the's @ POST's, the's @ PUT's, the's @ DELETE's.

Is @ Produces @ Consumes @ marking supported media types.

Is @ QueryParam @ PATHPARAM @ HEADERPARAM @ a, a mark request parameter.

Collecting endpoint information for each found JAX-RS endpoint, the following information is collected:

the full qualified name of the endpoint class. Signature of the endpoint method. The HTTP method of the request. The requested path template. Supported media types.

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

In the embodiment S104 of the present specification, the Swagger annotation may include an entry, a return value and a request description about the operation, and a description about the relevant controller, which may be implemented by the following specific embodiments:

Defining Swagger annotations determining which Swagger annotations are necessary, including:

is used for the controller class to provide basic information of the Api.

Is @ ApiOperation @ for the method, a description of the operation is provided.

Is @ ApiParam @ for the method parameters, providing a description of the parameters.

Is @ ApiResponse @ for the method, provides a description of the response.

Is @ ApiResponses @ for the method, providing a set of possible responses.

Is @ ApiVersion @ for the controller class, providing a version of the API.

And obtaining JAX-RS endpoint information, namely analyzing the Java source file by using a Java analyzer to find all JAX-RS HTTP endpoints.

Checking Swagger notes for each JAX-RS endpoint, the following checks are performed:

for the controller class, it is checked whether the port@Api 'annotation is used and whether necessary information (e.g., port value's, port produces's, port tags's, etc.) is provided. It is checked whether the 'ApiVersion' annotation is used and whether version information is provided.

For the endpoint method it is checked whether the or @ ApiOperation' annotation is used and whether a description of the operation is provided. It is checked whether the 'ApiParam' annotation is used and whether a description is provided for each parameter. It is checked whether the 'ApiResponse' or 'ApiResponses' annotation is used and whether a description is provided for each response.

Recording the missing notes if the Swagger notes are found missing, the following information is recorded:

Names of the missing Swagger notes. Names of controller classes or endpoint methods that lack annotations. Necessary additional information such as desired annotation parameters.

S105, if the defect that the Swagger annotation is absent in the specified controller class or the specified available JAX-RS HTTP endpoint is detected, the corresponding annotation is automatically inserted, and the modified Java file is obtained.

In the example S105 of the present specification, the following specific embodiments may be adopted:

Defining Swagger annotation templates-creating a template string of Swagger annotations, these templates will dynamically populate parameters according to context.

And analyzing the Java file, namely loading and analyzing the designated Java file by using a code analysis library to generate an Abstract Syntax Tree (AST).

Identifying JAX-RS endpoints and methods by traversing AST, identifying all JAX-RS endpoint classes and methods, which typically carry annotations of @ Path, @ GET, @ POST, @ PUT, @ DELETE, etc.

Swagger annotation is checked for absence of Swagger annotation for each identified JAX-RS endpoint and method.

Automatically inserting Swagger annotations if it is found that the Swagger annotations are absent, inserting the corresponding annotations according to the defined template.

For the controller class, the @ Api annotation is checked and inserted.

For the method, the notes @ ApiOperation, @ ApiParam, @ ApiResponse, etc. are checked and inserted.

The modified file is saved and the modified AST is converted back to the Java source code string. This string is saved back to the original Java file or to a new file.

S106, submitting the modified Java file to the Git warehouse, and triggering a Maven compiling process of the multi-module item through a specified automation server to obtain a JAX-RS interface document.

In this description example S106, for the multi-module project, each module invokes the SWAGGER MAVEN plug in plug-in, and generates module-specific Swagger definition files, which are independent of each other, and each file contains an independent HTTP endpoint list and its referenced model, which is inconvenient for uniformly browsing and managing project documents. Therefore, the Swagger definition files of these modules are usually required to be merged in actual production.

Merging faces some problems, firstly, the Swagger definition of each module contains meta information such as names, contacts, versions and the like, and these need to be replaced with global information uniformly. Second, each module contains the models it uses, which are critical to the way HTTP endpoints are invoked, the model names of each module may conflict, so a unified model name needs to be used, and the models referenced by all modules HTTP endpoints are modified so that they can maintain the correct correspondence. In addition, there are differences in importance and affinity between modules, so that certain rules are followed when ordering documents, such as putting together documents of similar functional modules, putting important modules in front.

The invention provides some code logic for automatically calling the merging process of the code execution module Swagger at the end of Jekins compiling stage and calling a PDF rendering tool to render, output and archive the unified project Swagger document.

It should be noted that, for the above, the embodiments of the present specification provide further analysis contents, as follows:

in the embodiment of the specification, SWAGGER MAVEN Plugin can be used for scanning the Swagger notes of each module, outputting OpenAPI documents for each module, wherein each OpenAPI document comprises an independent HTTP endpoint list and a model referenced by each OpenAPI document, and triggering own Maven Plugin code logic to combine the OpenAPI documents to obtain a JAX-RS interface document.

In the above, the following embodiments may be mentioned:

Configuration SWAGGER MAVEN Plugin A SWAGGER MAVEN Plugin configuration can be added to the pon.xml file of all modules.

Generating an OpenAPI document the following Maven commands are executed under the project's root directory to generate the OpenAPI document for all modules.

Establishing a custom Maven plug in, namely establishing a custom Maven plug in for merging OpenAPI documents of all modules. The following is the basic steps for creating a custom plug in:

Mojo defining Plugin:

A Java class inherited from org.apache.maven.plug in.Abstract Mojo is created and the objects and configuration of the plug-in are defined.

Implementing the merge logic-implementing the merge logic in Mojo classes, reading the OpenAPI documents of all modules, and then merging them into one document.

Configuration output-the configuration of the plug-in output, e.g., output directory, is defined.

Registration Mojo the execution targets and configuration parameters of the plug-in are defined using @ Mojo notes on the Mojo class of plug in.

And (3) configuring the custom Plugin, namely adding the configuration of the custom Plugin into the pon.xml of the root directory of the project.

Merging the OpenAPI documents, namely executing a specified Maven command to trigger the custom plug in and merging the OpenAPI documents.

Further, when the own Maven plug in code logic is triggered to merge the OpenAPI documents to obtain the JAX-RS interface document, the own Maven plug in code logic may be triggered to uniformly replace the Swagger definition of each module with global information, where the Swagger definition includes the name, the contact and the version of each module, the own Maven plug in code logic is triggered to merge the models corresponding to each module to globally unify the names of the usage models of each module, and the own Maven plug in code logic is triggered to sort the OpenAPI documents of each module according to preset rules to obtain the JAX-RS interface document.

Further, swagger documents provide descriptions about all HTTP endpoints, while a significant portion of the interfaces are limited to internal use for security or other purposes, so that they need to be classified as exposable and to be hidden according to a policy, and then the HTTP endpoints to be hidden are masked off, showing only the parts that are exposed, which can be exposed.

In view of the above, in the OpenAPI document, the embodiments of the present disclosure may obtain preset description information (equivalent to a certain policy) of all HTTP endpoints, and hide the corresponding interfaces according to the description information.

Further, the method further comprises adding additional description information in the OpenAPI document, wherein the additional description information comprises one or more of version description, interface use and security information.

Further, when the Maven compiling process of the multi-module item is triggered by the specified automation server to obtain the JAX-RS interface document, the Maven compiling process of the multi-module item can be triggered by the specified automation server to obtain the JSON-format OpenAPI document, and the JSON-format OpenAPI document is rendered by a PDF generating tool to obtain the JAX-RS interface document.

It should be noted that, in this embodiment of the present description, working from the Git commit hook trigger of project code, code logic is executed to find the controller class with JAX-RS tag that commits the modification, then parse the Java file and find each available JAX-RS HTTP endpoint, if the controller or endpoint lacks the Swagger annotation tag, insert these annotations to provide OpenAPI references to operations, return values and request descriptions, descriptions about the controller group, etc., the Git commit may be refused depending on the configuration. And then replacing the modified Java file, additionally supplementing and perfecting annotation information provided by default by a submitter, and finally submitting codes to a warehouse.

Code submitted to the repository triggers the CI/CD flow, which, in Jenkins for example, triggers the Maven compilation process of multi-module items, in which SWAGGER MAVEN plug in is used to scan the annotations of each module and output as an OpenAPI document for each module. Finally, the own Maven plug in code logic is triggered to merge these scattered OpenAPI documents, which includes merging the defined models for each module, replacing the old model for each module, hiding the internal HTTP endpoint from the extra remark information, adding other extra description information, and outputting as an integrated OpenAPI JSON format document. And finally, rendering and exporting the document through a PDF generation tool to construct a document of a final real-time reaction code JAX-RS interface. The process is shown in a flow diagram of a JAX-RS interface document automatic generation method in FIG. 2. In the figure, git submits code, then submits a checking tool, java grammar parsing, JAX-RS annotation checking, swagger annotation completion (which can be understood through ChatGPT code logic), further completion by a developer, CI/CD Maven compiling, a document filtering tool, document model merging, document definition replacement, document merging and PDF rendering.

It should be noted that the invention provides a fully-automatic JAX-RS interface document generation method, actions are executed when Git is submitted, and are triggered when CI/CD flows are compiled, so that a readable PDF document is finally obtained, manual intervention is not needed in the whole process, more coordination resources are not needed for a plurality of team cooperation projects, communication cooperation cost can be effectively reduced, inconsistent behaviors of documents and software interfaces are reduced, internal endpoints are required to be hidden by the software interfaces, and various requirements such as combination and conversion are met, offline use of the software interfaces is required.

In addition, the invention provides a simple and automatic method for providing automatic interface document output for the old JAX-RS interface project, the code script finds all JAX-RS controller classes from the scan project, then understands the code intention, adds Swagger annotation to the code script and triggers the OpenAPI document of each module to be compiled and generated, and finally performs merging and outputs a single PDF document.

Fig. 3 is a schematic structural diagram of a JAX-RS interface document generating apparatus according to one or more embodiments of the present disclosure, which includes a code activating unit 301, a controller identifying unit 302, an available endpoint searching unit 303, an annotation checking unit 304, a file modifying unit 305, and a document generating unit 306.

A code activation unit 301 that activates corresponding code logic by submitting hooks when a specified Java file is submitted to the Git repository;

a controller identification unit 302 that scans the specified Java file through the code logic to identify a controller class with a JAX-RS tag;

an available endpoint lookup unit 303 parsing the syntax of the specified Java file through the code logic to find each available JAX-RS HTTP endpoint;

An annotation checking unit 304 for checking, by said code logic, whether the or each available JAX-RS HTTP endpoint lacks Swagger annotations;

The file modification unit 305 automatically inserts corresponding annotations if checking that the specified controller class or the specified available JAX-RS HTTP endpoint lacks Swagger annotations, and obtains a modified Java file;

And the document generation unit 306 submits the modified Java file to the Git warehouse, and triggers a Maven compiling process of the multi-module item through a specified automation server to obtain a JAX-RS interface document.

FIG. 4 is a schematic structural diagram of a JAX-RS interface document generating device according to one or more embodiments of the present disclosure, including:

at least one processor, and

A memory communicatively coupled to the at least one processor, wherein,

In this specification, each embodiment is described in a progressive manner, and identical and similar parts of each embodiment are all referred to each other, and each embodiment mainly describes differences from other embodiments. In particular, for apparatus, devices, non-volatile computer storage medium embodiments, the description is relatively simple, as it is substantially similar to method embodiments, with reference to the section of the method embodiments being relevant.

Claims

1. A JAX-RS interface document generation method, comprising:

2. The method of claim 1, wherein the Swagger annotation includes an entry, return value and request specification for an operation, and a specification for an associated controller.

3. The method according to claim 1, wherein triggering the Maven compilation process of multi-module items by the specified automation server results in a JAX-RS interface document, comprising:

4. The method of claim 3, wherein triggering the native Maven plug in code logic to merge OpenAPI documents to obtain a JAX-RS interface document comprises:

5. The method according to claim 4, wherein the method further comprises:

6. The method according to claim 4, wherein the method further comprises:

7. The method according to claim 1, wherein triggering the Maven compilation process of multi-module items by the specified automation server results in a JAX-RS interface document, comprising:

8. A JAX-RS interface document generating apparatus, comprising:

9. A JAX-RS interface document generating apparatus, comprising:

at least one processor, and

A memory communicatively coupled to the at least one processor, wherein,

10. A non-transitory computer storage medium storing computer executable instructions that when executed by a computer enable: