Finally, you don't have to bother writing documents! How to generate API documentation that can be debugged

Finally, you don't have to bother writing documents! How to generate API documentation that can be debugged

What is written in this article? Always write documents. Code cannot be maintained without writing, soHave to write. But write the documentTime-consuming and labor-consumingWhat's even more terrible is that it is still difficult to finish writing and reading,Shelve, Total timeWasteDropped.Miserable. I have been suffering from "writing documents" for a long time. I accidentally saw an articleShenwenAnd then I checked it online.Automated toolsAndDSLTheory! Although most of them do not understand, it is enough to easily write a good document! Now let's talk about how I got it! What should I do? Our ultimate goal is to writeGoodDocumentation. Therefore, we must first determine:What is a good document?. Good documentation is shown in: The above documentGood News? First, it isDocumentTo let you know its functions and parameters at a glance; Secondly, it isProgramYou can enter a parameter to view the result immediately. So what I want is that after the code is completedSmall feeAs mentioned aboveDebuggableDocumentation. Let's do two things: 1. generate documents; 2. the document is debuggable. How? Now I want to start. I always feel a little bitNo way to startFromMost specificThe only debuggable API that can be viewed at present. The final debuggable APIWhat is it?What about it? Refer to the previous,SimplifiedSome of them look like this: Class name, method, function explanation, and input parameter for text display; There is an execution button; The execution result is displayed in one area. In this interface, what areVariableWhat about it? Class name List items Method name Function description Parameter quantity Parameter name Execution result One API corresponds to a class name, a method name, a function description, and multiple parameter names. 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 contains attributes: class name, path of the class file, method name, function description, and parameters required for this method. A parameter also contains attributes: parameter name and parameter description. Event Stream Next, we will analyze the entire transaction process. One sentenceProcess: Click "generate" to generate the HTML document of the class. This is what we have to do, but it is not clear. We want to generate an HTML document corresponding to a method of a class, but it is not clear in one sentence. Now we need to explain it clearly, so we can expand itA passage: The class and method of the document to be generated have been specified in the configuration file. click "generate" to read the configuration file and generate the document in sequence. Next, we will continue to expand until we can figure out all the steps. Final design There are three types of pages in the system: Feature Page: There is only one button to generate an API; Class list page: List the class and its method, and click it to jump to the API page. API page: Lists the methods. you can enter a parameter and execute this method to view the execution result. Among the three types of pages, the second type of list page does not have any function. it only involves Page jump, so only html is used for implementation. Both the function page and API page useMVC modeDesign. Feature Page MVC structure Model: API; View: make_api_template.php; Controller: create_api.php MVC call process When you click "generate" on The View layer, the Controller is triggered; The Controller specifies the class for generating the API, and calls the static method make_api in these classes to generate the Model; Controller uses these models to generate documents API page MVC structure Model: js code. an independent model has not yet been formed; View: the generated html page; Controller: index. php MVC call process At the View layer, the user enters the parameters of a method and clicks the "execute" button to trigger the Controller; The Controller executes the method based on the parameters on The View page and returns the result to the View; View receives and displays the result Conclusion The version I implemented isCohenBible. There are many similar tools, such as prmd, swagger editor, and apidocjs. Writing this article does not encourage everyoneDuplicate wheel creationBut once implemented by yourself, there will beDifferent. Why do I think of repeating the wheel? The biggest reason is:I really don't want to use the following tools.You have to implement the entire document generation process by yourself. As a result, I can go back and look at the above tools! For official tutorials, I don't know how much time it will take, haha :)

How to use APIs