Finally no more hard to write the document! teaches you how to generate a debug API document

What is written in this article? Always write documents. Do not write, code can not be maintained, so have to write . But writing documents takes time and effort , and what's more scary is that it's hard to read, and it's a pain in the neck to waste it. has been deeply "writing documents" torture, accidentally saw an article Shenwen , and then on the Internet and check the Automation tools and DSL theory, this is enlightened! Although most of them do not understand, but to do easy to write good documents, enough! Now let's talk about how I did it! What do you want to do? Our ultimate goal is to write good documentation. So, first we need to determine: What is a good document . The good document is as follows: where is the document above? First of all, it is the document that lets you know its function, parameters, at a glance; Second, it is a program , you can enter parameters to see the results immediately. So what I want to do is, after the code is done, it takes a little effort to generate a debug document like the one described above. We're going to do two things next: 1, generate documents; 2. Documentation is a document that can be debugged. What do you do? Now to start to do, always feel a little bit, then start from the most specific things-the only one can see the debugging API to begin to analyze it. What is the Debug API we're going to make? Refer to the previous, simplifying Some, is the following look: Plain text Display class name, method, function explanation, input parameters; There is an execution button; There is an area that shows the execution results. In this interface, what are the variables ? Class name List items Method name Function description Number of parameters Name of parameter Execution results Where: An API corresponds to a class name, a method name, a function description, multiple parameter names, execution results are generated after execution. Model analysis Based on the above results, I can abstract this API into a model class: An API contains attributes: The class name, the path to the class file, the method name, the description of the function, and the parameters that the method needs to input. And a parameter contains the attributes: Parameter name and parameter description. Event Flow Next, analyze the entire transaction flow. Word Flow: Click the "Generate" button to generate the HTML document for the class. That's what we're going to do, but it's not clear. We're going to generate an HTML document for one of the methods of a class, but there's no clear word. Now we have to explain it, and expand it into a phrase : The class for the document to be generated and its methods are specified in the configuration file, click the Generate button, read the configuration file, and then generate the document in turn. We continue to expand as we go on, until we have all the steps to clear up. Final design The whole system has a total of three categories of pages: Features page : Only one button to generate API; Class List page : List the class and its methods, and click to jump to the API page. API Pages : Lists method descriptions, you can enter parameters and execute the method to see the results of their execution. In the three categories of pages, the second class of Class list page has no function, only involves the page jump, so only the HTML implementation of the line. The feature pages and API pages are designed using the MVC pattern . Features page MVC structure Model:api; View:make_api_template.php; Controller:create_api.php MVC Call Flow When the user clicks the "Generate" button on the view layer, the controller is triggered; The controller specifies the classes that need to generate the API, and calls the static methods in these classes MAKE_API to generate the model; Controller uses these model to generate documents API Page MVC structure Model:js code, has not yet formed an independent model; View: the generated HTML page; Controller:index.php MVC Call Flow The user enters the parameter of a method in the view layer, and then clicks the "Execute" button to trigger the controller; Controller according to the parameters of the view page, the execution method, the results are returned to the view; The view receives the result and displays it Conclusion The version I implemented is cohenbible. A lot of similar tools, Prmd,swagger Editor, APIDOCJS, are very useful. Writing this article is not to encourage you to repeat the wheel , but to achieve it once again, there will be a different harvest. Why would I think of repeating the wheel? In fact, the biggest reason is: really do not use the above several tools , had to achieve their own implementation, the entire process of generating documents went through. As a result, back to look at the above tools, unexpectedly bring it to use! If it is to follow the official tutorial walk, do not know how much time to spend, haha:)

Teach you how, again, the bitter force, API

