Finally, you no longer have to work hard to write documents! Teach you how to generate debuggable API documentation

What is this article about?

I always have to write documents. Without writing, the code cannot be maintained, so have to write. But writing the document is time-consuming and labor-intensive , and what’s even more frightening is that it’s still very difficult to read after writing, shelving it on the shelf , I always feel that time is wasted , it’s really miserable .

I have always been tortured by "writing documents". I accidentally read an divine article, and then checked the theories of automation tools and DSL on the Internet, and then I had a sudden enlightenment! Although I don’t understand most of them, it’s enough if you want to write good documents easily!

Now let’s talk about how I did it!

What to do?

Our ultimate goal is to write gooddocuments. So, first we need to determine: What is a good document.

A good document is as shown below:

What’s so good about the above document? First of all, it is a
document, which lets you know its functions and parameters at a glance; Secondly, it is a
program, you can input the parameters and see the results immediately.

So, what I hope is that after completing the code, I can generate a

debuggable document like the one mentioned above with very little effort. We have to do two things next:

1. Generate documentation;

2. The documentation is debuggable.
How to do it?
Now I’m about to start, but I always feel like I don’t know where to start

, so let’s start with the

most specific thing—the only visible debuggable API at present. What kind of debuggable APIshould we finally make

?

Refer to the previous renderings, simplify

in some words, it looks like this:

Plain text displays the class name, method, function explanation, and input parameters; There is an execution button;

There is an area to display the execution results.

In this interface, what are the
variables

?

Class name

List items

Method name

Function Description

Number of parameters

Parameter name

Execution results

Among them: an API corresponds to a class name, a method name, a function description, multiple parameter names, and the execution result is generated after execution.

Model analysis

Based on the above results, I can abstract this API into a model class:

An API includes attributes: class name, path to the class file, method name, function description, and parameters that need to be input to the method.

A parameter also contains attributes: parameter name and parameter description.

event stream

Next, let’s analyze the entire transaction process.

In one sentence

Process:

Click the "Generate" button to generate the HTML document of the class. This is what we want to do, but it’s very unclear. We want to generate an HTML document corresponding to a certain method of a certain class, but we don't have a clear explanation in one sentence.
Now we want to explain it clearly, so we expanded it into
a paragraph

:

The class and method of the document to be generated have been specified in the configuration file. Click the "Generate button" to read the configuration file. Then generate documents in sequence. We will continue to expand in this way until all the steps are clear. final design
There are three types of pages in the entire system:

Function page

: There is only one button to generate API;

Class list page

: List the classes and their methods, click to jump to the API page.

API page

: Lists method descriptions, you can enter parameters and execute the method, and you can view its execution results.

Among the three types of pages, the second type list page has no function and only involves page jumps, so it can only be implemented in HTML. As for the function pages and API pages, they are designed using the

MVC pattern

.
Function page

MVC structure

Model:API;View:make_api_template.php;Controller:create_api.php


MVC call process

After the user clicks the "Generate" button on the View layer, the Controller is triggered; Controller specifies the classes that need to generate APIs, and calls the static method make_api in these classes to generate Models; Controller uses these Models Generate documentation

API page

MVC structure

Model: js code, which has not yet formed an independent model; View: generated html page; Controller: index.php


MVC calling process

The user inputs the parameters of a method in the View layer, and clicks the "Execute" button to trigger the Controller; Controller executes the method based on the parameters passed by the View page, and returns the result to the View; View receives Result and display it
Conclusion

The version I implemented is CohenBible.

There are many similar tools, prmd, swagger editor, apidocjs, all of them are very useful.
Writing this article is not to encourage everyone to reinvent the wheel, but if you implement it yourself, you will have different harvests.

Why would I think of reinventing the wheel?
In fact, the biggest reason is: I really don’t know how to use the above tools, so I had to implement it myself and go through the entire document generation process. As a result, when I look back at the tools above, I can actually use them right away! If you follow the official tutorial, I don’t know how much time it will take, haha:)

Teach you how, no matter how hard it is, API