ApiLeaf is probably the most effortless document generation tool ever

Introduction to the

I believe that many students who write background interface are like me, who have a headache for the compilation of interface documentation: it is time-consuming and laborious to write documentation, which is really a blow to the development enthusiasm of developers, especially in the agile development of small and medium-sized projects, often writing documentation takes longer than the interface development time.

For large projects and mature teams, there are mature interface automation testing tools that combine interface testing, automated builds, and mock data, but small and medium development teams (such as student organizations) often don’t have the ability to build similar platforms.

As a result, many people simply don’t leave documents, which increases the communication costs at the front and back end and reduces the team’s productivity.

What is called “lazy, is the first power of human progress”, in line with the documentation as much as possible, reduce work lazy, I’m trying to develop this document generation tools and management platform: ApiLeaf, if you are a small team of back-end developers, also like I don’t like to write documents, just to see if it can help to you!

The core idea

So-called API documentation, is nothing more than for interface request = > a detailed description and explanation of the process, for the back-end developers, this process is the process of our daily test interface, so as long as the recording and playback, the test process to attach some necessary instructions, not can be used as a document?

For example, we now have A calculation of A + B interface, the request URL for http://localhost:8080/add, need to do A test for it, so we POST the following data:

{
	"a": 1,
	"b"2} :Copy the code

Then we get a successful response from the server:

{
	"code": 0."result": 3}Copy the code

Now that we’re done testing the interface, let’s see what data we can get from this process:

• The requested URL
• The requested Method is Method
• Request header Headers
• Request the structure of the Body Body
• A correct request demonstration

As well as

• The response Headers
• The structure of the response Body
• An example of a correct response

This is more than enough to document the interface, and it is usually only necessary to add some basic descriptions for each field in Headers and Body to produce a fairly detailed document.

ApiLeaf was based on such a train of thought, as long as you are conducted on ApiLeaf interface test, it can record the requests and responses in the process of test data, and automatically build the document structure, the foundation of the majority of cases you just need to add some basic description (if you use a function, the article introduces the data dictionary even don’t have to fill in the description). You can generate documents quickly.

Document automatic generation demonstration

Go to ApiLeaf, register and log in to your account, and then click on the main panel of the home page to enter your personal panel.

The personal panel provides a document management interface, and before we can start trying to automate document generation, we need to set up a project.

In the project panel I created, click New Project to create a project. All you need to do is fill in the project name and description:

Click on the drop-down menu in the upper right corner and select Launch test to enter the HTTP test panel. You will see a postman-like interface.

This interface receives a login_name and a password, and returns the basic model of the logon user on success. We add the URL and Body of the request, and then we can send the request for HTTP testing:

Api Leaf uses fetch to send this request, so you can use it to test the local interface and simulate the real world of front-end requests to the best of your ability, with a little care for cross-domain issues.

If the test is successful, you can see the Response from the server in the Response panel below:

If the test fails and the response cannot be obtained, you can open the browser console to trace the cause of the fetch request.

Now we can click Generate document to go to the edit page of the interface document

First of all, we need to supplement the basic information of the interface. Select the project to which the interface belongs (the document of the interface will be automatically included in the general document of the project after it is generated). The URL and METHOD have been automatically filled in, and you can just add the name and description. You can also assign a group name to the interface, which is used to categorize the interface across the project, which is useful when there are many project interfaces.

Next we will see a number of JSON editors. ApiLeaf will divide the data collected from the previous test into the following seven sections and automatically populate the corresponding sections in the editor:

• API Request Headers
• API Request parameters (QueryString)
• API request Body
• API request Demonstration
• API response Headers
• API Response Body
• API Response Demonstration

In the example of the previous test, the response body edit box will be filled with the following content

[{"body_key": "code"."body_type": "integer"."body_description": ""
	},
	{
		"body_key": "user"."body_type": "object"."body_description": ""
	},
	{
		"body_key": "user.id"."body_type": "integer"."body_description": ""
	},
	{
		"body_key": "user.name"."body_type": "string"."body_description": ""
	},
	{
		"body_key": "user.sex"."body_type": "string"."body_description": ""
	},
	{
		"body_key": "user.age"."body_type": "integer"."body_description": ""}]Copy the code

ApiLeaf pulls out all the keys in the response JSON to build a hierarchy (to. Split) and automatically infer their data type, all you need to do is check whether the body_type is correct and add the body_description field description.

For the rest of the content, similar JSON is generated and filled into the corresponding editor, and you just need to complete them as if they were fill-in-the-blank. For parts that are not needed, I can uncheck them so that the document does not contain the content of the response part. For example, in this API, I only need to check the request body, the response body and its demonstration.

Note that the contents of the edit box must be valid JSON, and there are requirements for the key of each field, so please do not modify the structure of the contained object, otherwise it may cause errors.

After completing these simple fill-in-the-blank questions, the document is ready to be generated and you should see a preview of the API document:

The request and response tabs are provided to display the corresponding description.

At this point, the document generation of a structure is complete, and ideally, the test + document generation process takes less than 1 minute, which is very convenient.

If this is still a hassle and you don’t want to fill in a lot of blanks, check out the data dictionary section below. If used wisely, you can generate a complete document without even filling in anything!

Data dictionary with automatic matching

Data dictionary, it is to point to in a project frequently used basic data structures, such as just the User object in the test project, as a basic definition of User data, may be in a lot of the interface will be used, if use the Api Leaf automatically generated document, is likely to need to repeat to fill in all fields of the User instructions for many times, this is we can’t accept it.

The idea of Api Leaf is to create commonly used data structures into data dictionaries and save them in the project. On the one hand, it is convenient for front-end personnel to quickly obtain commonly used data structure definitions. On the other hand, when data structures repeat, relevant dictionaries can be automatically matched, so as to reduce the process of repeated writing instructions.

With that said, let’s take a look at how data dictionaries are used:

Create a data dictionary

Enter the document viewing page of the specified project, click the data dictionary in the top navigation bar to enter the list page of the data dictionary, and then click the Add New dictionary button to enter the edit page of the data dictionary:

After filling in the type name and description of the data dictionary on the edit page (note that you can’t have two data dictionaries with the same type name in a project), you can manually supplement the field definitions and description of the data dictionary, or you can parse a data dictionary from a sample JSON file.

For example, we use the User object JSON returned in the response to create this data dictionary:

Click Parse to automatically add all field names and types. You need to manually check if these types are correct and add the corresponding description:

Finally, click the Done button to generate a complete data dictionary.

Automatic matching

Now that we have a data dictionary, let’s look at how to use automatch.

Suppose we now have another interface in the project, /user/{id}/profile, through which we can obtain the personal information of the specified user (that is, his user model). Then we run a test and get the following response:

{
	"code": 0."user": {
		"id": 17."name": "lumin"."sex": "male"."age"20}} :Copy the code

Now we need to generate the document, at this time you find that the user type has been defined in the previous login interface, do you need to write the description of each field again?

The answer is NO, as long as you have defined the data structure into the data dictionary, you do not need to fill in any body_description field at this stage, just click Generate document, and then go to the view page of the project document. You will find several more buttons in the description field of the response.

Then click the button and something magical happens: Api Leaf will automatically go to the project’s data dictionary to match the most likely data definition, based on all the keys of the selected field. In this case, we will get a 100% match for the User data definition. Yes, that’s what we need!

The matching function will search for the most similar structures in the data dictionary as possible, but it may not be found or the matching rate may be very low, such as the following:

Matched fields are displayed in bold.

When the match rate is below 60%, there is a good chance that this is not the data definition you need, so it is better to supplement the data dictionary or field definition

Once you’ve defined a common data dictionary, you’ll save a lot of effort in document generation, so once you’ve created your project’s basic data definitions (such as database table structures), add them to the data dictionary.

Pay attention to

Currently, the data dictionary does not support nested hierarchical field definitions, and the matching results are only for reference. It is recommended that the front and back ends communicate with each other before using this function.

A complete document structure

Now that we’ve covered the basic process of creating a project document using Api Leaf, let’s take a look at what a complete project document can provide from the front end/client developer’s perspective.

You can click here to see a simple demonstration document provided by the authorities.

A complete project document in Api Leaf includes the following three parts:

1. API interface documentation: Generated and aggregated by HTTP tests
2. Status code list: The various status codes used in the project
3. Data dictionary: Commonly used data structure definitions

The navigation bar at the top allows you to quickly switch between the three sections, and each section provides a navigation bar on the left for quickly locating the relevant definitions:

The API interface document part also provides grouping, sorting, screening and other functions. In order to facilitate readers to find documents, we also provide a favorite function, which can save the recently frequently used documents.

other

Api Leaf also provides other features, such as teamwork, that won’t be covered here, but please check the documentation for more details.

This is the first open source tool I have made, which is designed and developed for the use of my own team, but I believe that most small and medium-sized agile development teams like ours, especially student teams, need such a tool to facilitate communication and communication between members.

Since it is a personal independent development, there are still areas to be polished in terms of beautiful pages and logic of use. I will continue to update and optimize related functions in the future.

Welcome developers to try and put forward valuable advice!

• Author: Liu Ming @Not Washing Dishes Studio
• github：https://github.com/MarkLux/ApiLeaf

By the way, I buried some eggs on the page, if you are interested, you can find them