Method, device and server for generating web-based interface documentation

Abstract

The method comprises the following steps: obtaining the annotation, the routing information and the environment information of a preconfigured interface; analyzing the function object of the interface in the source code according to the annotation, and determining the first request body and the first response body under the routing information; and generating the interface document of the interface according to the first request body, the first response body, the routing information and the environment information. The method provided by the present disclosure can analyze the function object of the interface through the preset annotation of the interface, obtain the first request body and the first response body, and further obtain the interface document. The method provides a general interface document generation method, and because the interface document and the function object use the same declaration part, the generated interface document can be synchronized with the business code, thereby reducing the workload of the developer in developing and maintaining the interface document.

Description

Technical Field

[0001] This disclosure relates to computer technology, and more particularly to a method, apparatus, and server for generating web-based interface documents. Background Technology

[0002] Currently, application front-ends and back-ends can interact and exchange data through Application Programming Interfaces (APIs). Providing front-end developers with accurate API documentation quickly helps improve collaboration efficiency between front-end and back-end developers.

[0003] In the current technology, the Swagger framework is a widely used framework for automatically generating API documentation. API documentation can be generated using various language plugins of Swagger, along with some configuration or code.

[0004] However, the above methods are not flexible enough due to their binding to the framework, and often require adding a lot of extra code to describe the interface parameters, which increases the workload of developers in developing and maintaining interface documentation. Summary of the Invention

[0005] This disclosure provides a method, apparatus, and server for generating web-based interface documentation, thereby improving the flexibility of generating interface documentation in the prior art and reducing the workload of developers in developing and maintaining interface documentation.

[0006] According to a first aspect of this disclosure, a method for generating web-based interface documentation is provided, comprising:

[0007] Obtain the interface debugging request sent by the web client, and obtain the pre-configured interface annotations, routing information, and environment information based on the interface debugging request;

[0008] Based on the annotation, the function object in the source code corresponding to the interface is parsed, and the first request body and the first response body under the routing information are determined;

[0009] Based on the first request body, the first response body, the routing information, and the environment information, an interface document for the interface is generated; and the interface document is returned to the web client.

[0010] According to a second aspect of this disclosure, an apparatus for generating web-based interface documentation is provided, comprising:

[0011] The acquisition unit is used to acquire the interface debugging request sent by the web client, and to acquire the pre-configured interface annotations, routing information, and environment information according to the interface debugging request;

[0012] The parsing unit is used to parse the function object in the source code corresponding to the interface according to the annotation, and determine the first request body and the first response body under the routing information;

[0013] The generation unit is configured to generate an interface document for the interface based on the first request body, the first response body, the routing information, and the environment information; and return the interface document to the web client.

[0014] According to a third aspect of this disclosure, a server is provided, including a memory and a processor; wherein,

[0015] The memory is used to store computer programs;

[0016] The processor is configured to read a computer program stored in the memory and execute the web-based interface document generation method as described in the first aspect, based on the computer program in the memory.

[0017] According to a fourth aspect of this disclosure, a computer-readable storage medium is provided, wherein computer-executable instructions are stored therein, and when a processor executes the computer-executable instructions, the method for generating a web-based interface document as described in the first aspect is implemented.

[0018] According to a fifth aspect of this disclosure, a computer program product is provided, including a computer program that, when executed by a processor, implements the method for generating web-based interface documentation as described in the first aspect.

[0019] This disclosure provides a web-based interface documentation generation method, apparatus, and server, comprising: obtaining an interface debugging request sent by a web client; obtaining pre-configured interface annotations, routing information, and environment information based on the interface debugging request; parsing the function object corresponding to the interface in the source code based on the annotations, and determining the first request body and first response body under the routing information; generating the interface documentation based on the first request body, first response body, routing information, and environment information; and returning the interface documentation to the web client. In this solution, the web-based interface documentation generation method, apparatus, and server can parse the function object of the interface using pre-defined annotations to obtain the first request body and first response body, thereby obtaining the interface documentation. This solution provides a general method for generating interface documentation, and because the interface documentation and function objects use the same declaration section, the generated interface documentation can be synchronized with the business code. This reduces the workload of developers in developing and maintaining interface documentation. Attached Figure Description

[0020] To more clearly illustrate the technical solutions in the embodiments of this disclosure or the prior art, the drawings used in the description of the embodiments or the prior art will be briefly introduced below. Obviously, the drawings described below are only some embodiments of this disclosure. For those skilled in the art, other drawings can be obtained based on these drawings without creative effort.

[0021] Figure 1 This is a schematic flowchart illustrating a method for generating web-based interface documentation, which is an exemplary embodiment of this disclosure.

[0022] Figure 2 A schematic flowchart illustrating a method for generating web-based interface documentation, as shown in another exemplary embodiment of this disclosure;

[0023] Figure 3 This is a schematic diagram illustrating the process of generating a web-based interface document, which is an exemplary embodiment of this disclosure.

[0024] Figure 4 This is a structural diagram of a webpage-based interface document generation apparatus, illustrating an exemplary embodiment of the present disclosure.

[0025] Figure 5 A structural diagram of a webpage-based interface document generation apparatus is shown as another exemplary embodiment of this disclosure;

[0026] Figure 6 This is a structural diagram of an electronic device illustrated in an exemplary embodiment of the present disclosure. Detailed Implementation

[0027] Currently, application front-ends and back-ends can interact and exchange data via APIs. Providing accurate API documentation quickly to front-end developers helps improve collaboration efficiency between them. Traditional API documentation is typically written using Word or API documentation management platforms, but maintaining and updating such documentation is cumbersome; every time the API changes, the documentation needs to be manually modified. Therefore, the Swagger framework was developed to manage API documentation. Its overall goal is to ensure that the client and the file system source code are updated at the same speed as the server, automatically updating the corresponding API documentation when the API changes.

[0028] Currently, there are two main ways to use Swagger: The first is to define a YAML file to maintain all the information about the API. For example, the Flask Swagger approach. Flask Swagger is based on Python docstrings, using comments to write the Swagger YAML definition to generate API documentation.

[0029] However, while comment-based Flask Swagger can accurately describe API behavior and requirements, it suffers from the following significant problems: 1. The API documentation is disconnected from the code, requiring developers to update comments simultaneously with code updates. 2. Excessive comments occupy most of the code page, obscuring the actual business logic and hindering code readability. 3. Precise formatting is required, lacking features like indentation and tooltips, consuming developer time and effort in debugging the documentation's declaration format.

[0030] The second way to use Swagger is through various language plugins, along with some configuration or a small amount of code, which then translate the code into Swagger YAML definition files, thereby generating API documentation. For example, the drf-yasg method. drf-yasg is an extension of Django-Rest-Framework, specifically designed for the Django web framework. It can automatically extract API routing information from the code and generate OpenAPI / Swagger documentation based on the Django REST framework's proprietary APIView view definition. For some custom APIs, additional decorators or documentation comments are needed to assist in the generation process.

[0031] However, while drf-yasg, a framework plugin, can generate Swagger documentation relatively intelligently, it has obvious drawbacks: First, it is bound to the framework and lacks flexibility; second, the automatically generated interface documentation is difficult to fully meet the developers' expectations, often requiring the addition of a lot of extra code to explain the interface parameters, which increases the workload of developers in developing and maintaining interface documentation.

[0032] To address the aforementioned technical issues, the solution provided in this disclosure allows for the parsing of function objects through pre-defined annotations on the interface, yielding the first request body and the first response body, and subsequently, the interface documentation. This solution offers a universal method for generating interface documentation. Because the interface documentation and function objects use the same declaration sections, the generated interface documentation can be synchronized with the business code, eliminating the need for additional code to explain interface parameters. This reduces the workload for developers in developing and maintaining interface documentation. Furthermore, it requires minimal comments and eliminates the need to debug the documentation's declaration format.

[0033] The technical solutions of this disclosure and how they solve the aforementioned technical problems will be described in detail below with specific embodiments. These specific embodiments can be combined with each other, and the same or similar concepts or processes may not be repeated in some embodiments. The embodiments of this disclosure will now be described with reference to the accompanying drawings.

[0034] Figure 1 This is a schematic flowchart illustrating a method for generating web-based interface documentation, which is an exemplary embodiment of this disclosure.

[0035] like Figure 1 As shown, the web-based interface documentation generation method provided in this embodiment includes:

[0036] Step 101: Obtain the interface debugging request sent by the web client, and obtain the pre-configured interface annotations, routing information, and environment information based on the interface debugging request.

[0037] The method provided in this disclosure can be executed by an electronic device with computing capabilities, such as a computer.

[0038] Specifically, the annotations, routing information, and environment information of the interface can be pre-configured as needed. Then, the electronic device can obtain the interface debugging request sent by the web client and obtain the annotations, routing information, and environment information of these pre-configured interfaces based on the interface debugging request.

[0039] The interface's environment information is used to characterize the interface's global configuration and may include information such as title, version, and access address.

[0040] The routing information of the interface is used to represent the address information of the resource obtained through the interface.

[0041] Step 102: Based on the annotations, parse the function objects in the source code corresponding to the interface, and determine the first request body and the first response body under the routing information.

[0042] Specifically, the formats of the first request body and the first response body can be pre-configured.

[0043] Specifically, the source code corresponding to the interface can be obtained, and the function object corresponding to the interface can be extracted from the source code. Then, the extracted function object can be parsed using the annotations of the interface, and the first request body and the first response body under the routing information of the interface can be determined based on the parsing results.

[0044] Step 103: Generate the interface document based on the first request body, the first response body, the routing information, and the environment information; and return the interface document to the web client.

[0045] Specifically, the first request body, the first response body, and the pre-configured routing and environment information for the interface can be combined to generate the interface documentation. This documentation is then returned to the web client. The interface documentation can be used for debugging the interface.

[0046] This disclosure provides a method for generating web-based interface documentation, comprising: obtaining an interface debugging request sent by a web client, and obtaining pre-configured interface annotations, routing information, and environment information based on the interface debugging request; parsing the function object corresponding to the interface in the source code based on the annotations, and determining the first request body and the first response body under the routing information; generating the interface documentation based on the first request body, the first response body, the routing information, and the environment information; and returning the interface documentation to the web client. In this method, the function object can be parsed using the interface's pre-defined annotations to obtain the first request body and the first response body, thereby obtaining the interface documentation. This solution provides a general method for generating interface documentation, and because the interface documentation and function objects use the same declaration section, the generated interface documentation can be synchronized with the business code, eliminating the need to add extra code for interface parameter descriptions, thus reducing the workload of developers in developing and maintaining interface documentation. Furthermore, it requires no excessive comments and does not require debugging the document's declaration format.

[0047] Figure 2 This is a flowchart illustrating a method for generating web-based interface documentation, which is another exemplary embodiment of this disclosure.

[0048] like Figure 2 As shown, the web-based interface documentation generation method provided in this embodiment includes:

[0049] Step 201: Obtain the interface debugging request sent by the web client, and obtain the pre-configured interface annotations, routing information, and environment information based on the interface debugging request.

[0050] Specifically, the principle and implementation of step 201 are similar to those of step 101, and will not be repeated here.

[0051] Step 202: Obtain the function object corresponding to the interface in the source code; based on the input parameters, parse the function object corresponding to the interface in the source code and determine the first request body under the routing information; the annotation includes the input parameters and the return value.

[0052] Specifically, you can first obtain the function object corresponding to the interface in the source code, then parse the function object according to the input parameters included in the interface, and then determine the first request body under the routing information of the interface.

[0053] In one possible approach, the request body parameter names in the input function object are matched.

[0054] Specifically, the naming convention for request body parameters in the function object can be pre-configured. Then, input parameters can be matched one-to-one with the request body parameter names in the function object.

[0055] If a match is found, the data type of the parameter corresponding to the request body parameter name is obtained, and the first request body is determined based on the data type of the parameter.

[0056] Specifically, if the input parameter name is the same as the request body parameter name, it is determined that the input parameter name matches the request body parameter name. Then, the parameter data type corresponding to the request body parameter name can be obtained, and the first request body can be determined based on the parameter data type.

[0057] Step 203: Based on the return value, parse the function object in the source code corresponding to the interface and determine the first response body under the routing information.

[0058] Specifically, the function object can be parsed based on the return value of the interface to determine the first response body under the routing information of the interface.

[0059] In one possible approach, the return value is matched against the response body parameter name in the function object.

[0060] Specifically, the naming convention for the response body parameters in the function object can be pre-configured. This allows for a one-to-one matching of the return values ​​of the interface with the response body parameter names in the function object.

[0061] If a match is found, the response body data type corresponding to the response body parameter name is obtained, and the first response body is determined based on the response body data type.

[0062] Specifically, if the return value is the same as the response body parameter name, then it is determined that the return value matches the response body parameter name. The response body data type corresponding to the response body parameter name can then be obtained, and the first response body can be determined based on the response body data type.

[0063] Step 204: Encapsulate the first request body and the preset request information to obtain the second request body; encapsulate the first response body and the preset response information to obtain the second response body.

[0064] The preset request information is request information pre-set according to actual needs. The preset request information can be supplementary information to the request information contained in the first request body according to actual needs.

[0065] The preset response information is response information pre-set according to actual needs. The preset response information can be supplementary information to the response information contained in the first response body according to actual needs.

[0066] Specifically, the first request body and preset request information can be encapsulated to obtain the second request body. Similarly, the first response body and preset response information can be encapsulated to obtain the second response body.

[0067] Step 205: Generate the interface document based on the second request body, the second response body, the routing information, and the environment information; and return the interface document to the web client.

[0068] Specifically, the second request body, the second response body, and the pre-configured routing and environment information for the interface can be combined to generate the interface documentation, which is then returned to the web client.

[0069] Figure 3 This is a schematic diagram illustrating the process of generating a web-based interface document, which is an exemplary embodiment of this disclosure.

[0070] like Figure 3 As shown, you can pre-set and retrieve the interface's annotations, environment information, and routing information. Specifically, Python Enhancement Proposals 484 and 526 (PEP484 and 526) introduced type hints and variable annotation proposals, adding a type hint system similar to static languages ​​to Python, which is originally a dynamic programming language. This allows for writing more readable and maintainable code. After the introduction of type annotations, they are actually stored in the `annotations` variable on the Python function object. This annotation variable can contain information such as the values ​​and types of inputs and outputs, allowing you to extract the inputs and outputs relevant to the interface documentation, namely the first request body and the first response body. Therefore, after annotating a Python function with type annotations, you can retrieve the annotations through the `annotations` attribute. Simultaneously, you can use `openapi` to define decorators to obtain the interface's environment information. You can use route decorators to define the interface's path information. Multiple path information pieces form the global routing table. The global routing table is a virtual entity that can be obtained from the interfaces provided by the framework. Specifically, route decorators, usually provided by web frameworks, provide the path routing information for the API. OpenAPI decorators mainly provide additional information beyond parameters, responses, and routes; typically, only description and tag information are needed. API definition annotations define the input parameters and return values ​​of the API.

[0071] Specifically, a data object resolver can be used to parse the function object based on the annotations, extracting the parameter information required by the Swagger specification. Specifically, in the `annotations` dictionary, the key is the parameter name, and the value is the `type` or the specific annotation value. For the `type`, further parsing can be performed to extract class member variables, thereby obtaining the required first request body and first response body. The main process is: first, pass in the encapsulated function object, and then extract the data type corresponding to the annotation from the function object.

[0072] Specifically, the parameter names for the request and response bodies can be agreed upon in advance. In the RESTful specification, for GET request bodies, query semantics are typically used, with parameters generally identified by `parameter`. For other request bodies such as POST, parameters are usually identified using JSON / form, and the actual content is wrapped in the `body`, i.e., the request body. Combining this with annotation naming conventions, the naming can be agreed upon as follows:

[0073] query: The parameter name used in the GET request body.

[0074] body: Used for naming parameters in request bodies such as POST / DELETE / PATCH.

[0075] The response body defaults to "return" and requires no special specification. The annotation must contain the -> annotation.

[0076] Specifically, the request and response bodies can be pre-encapsulated as type objects. The request body typically includes many parameters; for example, a List request usually includes parameters such as `page_size`, `page_num`, `order_by`, and `filter_bys`; a POST update request typically includes parameters such as `xxx_id` and `new_values`. The response body also contains multiple parameters, such as `name`, `description`, and `create_time`. Therefore, these parameters need to be encapsulated into a class object for easier parsing. Currently, Python's `dataclass` and `pydantic` are ideal types for storing data objects, both capable of expressing similar semantics. They, or other similar techniques, can be used to encapsulate the request and response bodies. Furthermore, List requests can add the `filter_by` feature to extract other class member variables as filtering parameters. Specifically, the List class can, for example, add filtering based on whether it is effective, which can be achieved by inheriting from `PaginationRequestBase`. Other request bodies are similar; simply agree with the front-end on the necessary encapsulation content. The response body is handled in the same way, only replacing `pydantic` with `dataclass`.

[0077] Specifically, the response body can be pre-serialized and encapsulated. Typically, the response body contains not only the data retrieved from the backend but also additional information for the frontend. For example, a common response body includes the following: code (request status code); message (message description); data (returned data); and detail (other content for analysis, such as stack traces if an error occurs). Therefore, a response wrapper can be used to further encapsulate the response body, and type construction can be performed using metaclasses. Thus, the second request body can be obtained from the first request body, and the second response body can be obtained from the first response body, as described above.

[0078] Next, the OpenAPI assembler parses the second request body and the second response body, while also aggregating additional routing information, environmental data, etc., to assemble and build the OpenAPI documentation. Then, it parses the various OpenAPI definitions to generate Swagger documentation, thus obtaining the API's documentation. Specifically, besides the automatic parsing of parameters and return values, other Swagger definition parameters are parsed based on additional parameters provided by the decorator, which may include a summary (API description) and tags (API category). Therefore, combined with Python decorators, function annotations can be explicitly extracted and interpreted into Swagger documentation definitions, while simultaneously encapsulating the response body to achieve a WYSIWYG API documentation code definition that seamlessly integrates with business logic code.

[0079] Existing technologies do not use annotations for dynamic type resolution. Instead, they explicitly write Swagger YAML definition comments or bind to the framework, relying on member variables provided by the framework for resolution. While these methods can generate API documentation, they have significant limitations and the code and API documentation definitions are not fully integrated. This often requires maintaining both code and API documentation simultaneously, which can easily lead to oversights. The solution provided in this publication offers a universal method for generating API documentation for Python web frameworks, significantly reducing the workload of developers in developing and maintaining API documentation.

[0080] Figure 4 This is a structural diagram of a webpage-based interface document generation apparatus, illustrating an exemplary embodiment of the present disclosure.

[0081] like Figure 4 As shown, the web-based interface documentation generation apparatus 400 provided in this disclosure includes:

[0082] The acquisition unit 410 is used to acquire the interface debugging request sent by the web client, and to acquire the pre-configured interface annotations, routing information, and environment information according to the interface debugging request;

[0083] The parsing unit 420 is used to parse the function object in the source code corresponding to the interface according to the annotation, and determine the first request body and the first response body under the routing information;

[0084] The generation unit 430 is used to generate an interface document for the interface based on the first request body, the first response body, routing information, and environmental information; and return the interface document to the web client.

[0085] Figure 5 This is a structural diagram of a webpage-based interface document generation apparatus, illustrating another exemplary embodiment of the present disclosure.

[0086] like Figure 5 As shown, based on the above embodiments, the parsing unit 420 in the webpage-based interface document generation apparatus 500 provided in this disclosure further includes:

[0087] The parameter parsing module 421 is used to obtain the function object corresponding to the interface in the source code.

[0088] Based on the input parameters, the function object corresponding to the interface in the source code is parsed, and the first request body under the routing information is determined;

[0089] The return value parsing module 422 is used to parse the function object in the source code corresponding to the interface based on the return value and determine the first response body under the routing information.

[0090] The input parameter parsing module 421 is specifically used to match the input parameters with the request body parameter names in the function object;

[0091] If a match is found, the data type of the parameter corresponding to the request body parameter name is obtained, and the first request body is determined based on the data type of the parameter.

[0092] The return value parsing module 422 is specifically used to match the return value with the response body parameter names in the function object;

[0093] If a match is found, the response body data type corresponding to the response body parameter name is obtained, and the first response body is determined based on the response body data type.

[0094] The generation unit 430 is specifically used to encapsulate the first request body and preset request information to obtain the second request body;

[0095] The first response body and the preset response information are encapsulated to obtain the second response body;

[0096] Based on the second request body, the second response body, routing information, and environment information, generate the interface documentation for the interface.

[0097] Figure 6This is a structural diagram of a server shown as an exemplary embodiment of the present disclosure.

[0098] like Figure 6 As shown, the server provided in this embodiment includes:

[0099] Memory 601;

[0100] Processor 602; and

[0101] Computer programs;

[0102] The computer program is stored in memory 601 and configured to be executed by processor 602 to implement any of the above-described methods for generating web-based interface documents.

[0103] This embodiment also provides a computer-readable storage medium having a computer program stored thereon, the computer program being executed by a processor to implement any of the above-described methods for generating web-based interface documents.

[0104] This embodiment also provides a computer program product, including a computer program that, when executed by a processor, implements any of the above-described methods for generating web-based interface documents.

[0105] Those skilled in the art will understand that all or part of the steps of the above-described method embodiments can be implemented by hardware related to program instructions. The aforementioned program can be stored in a computer-readable storage medium. When executed, the program performs the steps of the above-described method embodiments; and the aforementioned storage medium includes various media capable of storing program code, such as ROM, RAM, magnetic disks, or optical disks.

[0106] Finally, it should be noted that the above embodiments are only used to illustrate the technical solutions of the present invention, and not to limit them; although the present invention has been described in detail with reference to the foregoing embodiments, those skilled in the art should understand that modifications can still be made to the technical solutions described in the foregoing embodiments, or equivalent substitutions can be made to some or all of the technical features; and these modifications or substitutions do not cause the essence of the corresponding technical solutions to deviate from the scope of the technical solutions of the embodiments of the present invention.

Claims

1. A method of generating an interface document based on a web page, characterized by, The method comprises the following steps: acquiring an interface debugging request sent by a web client, and acquiring an annotation, route information, and environment information of a pre-configured interface according to the interface debugging request; the annotation comprises an input parameter and a return value; acquiring a function object of the interface in source code; analyzing the function object of the interface in the source code according to the input parameter, and determining a first request body under the route information; analyzing the function object of the interface in the source code according to the return value, and determining a first response body under the route information; encapsulating the first request body and preset request information to obtain a second request body; encapsulating the first response body and preset response information to obtain a second response body; generating an interface document of the interface according to the second request body, the second response body, the route information, and the environment information; returning the interface document to the web client.

2. The method of claim 1, wherein, The step of analyzing the function object of the interface in the source code according to the input parameter, and determining a first request body under the route information, comprises the following steps: matching the input parameter with a request body parameter name in the function object; if the matching is successful, acquiring a parameter data type corresponding to the request body parameter name, and determining the first request body according to the parameter data type.

3. The method of claim 1, wherein, The step of analyzing the function object of the interface in the source code according to the return value, and determining a first response body under the route information, comprises the following steps: matching the return value with a response body parameter name in the function object; if the matching is successful, acquiring a response body data type corresponding to the response body parameter name, and determining the first response body according to the response body data type.

4. An apparatus for generating an interface document based on a web page, characterized by comprising: The method comprises the following steps: an acquiring unit is configured to acquire an interface debugging request sent by a web client, and acquire an annotation, route information, and environment information of a pre-configured interface according to the interface debugging request; the annotation comprises an input parameter and a return value; a parsing unit is configured to acquire a function object of the interface in source code; analyze the function object of the interface in the source code according to the input parameter, and determine a first request body under the route information; analyze the function object of the interface in the source code according to the return value, and determine a first response body under the route information; a generating unit is configured to encapsulate the first request body and preset request information to obtain a second request body; encapsulate the first response body and preset response information to obtain a second response body; generate an interface document of the interface according to the second request body, the second response body, the route information, and the environment information; and return the interface document to the web client. The method comprises the following steps:

5. A server, characterized by a memory and a processor are included; wherein the memory is configured to store a computer program; the processor is configured to read the computer program stored in the memory, and execute the method according to any one of claims 1-3 based on the computer program in the memory.

6. A computer-readable storage medium, characterized in that, The computer readable storage medium stores computer execution instructions, and when a processor executes the computer execution instructions, the method in any one of claims 1-3 is implemented.

7. A computer program product comprising a computer program, characterized in that, The computer program is executed by the processor, and the method in any one of claims 1-3 is implemented.

Images