Shulou(Shulou.com)06/02 Report--

This article mainly introduces "apidoc how to achieve automatic generation of API documents", in the daily operation, I believe that many people have doubts about how to achieve automatic generation of API documents in apidoc. The editor consulted all kinds of materials and sorted out simple and easy-to-use methods of operation. I hope it will be helpful for you to answer the doubts of "how to achieve automatic generation of API documents in apidoc". Next, please follow the editor to study!

Nowadays, it is becoming more and more popular to separate the front and back ends, which decouples the front and back ends. The connection between the front and back ends comes from the data interface, so the back end needs to write API interface documents to the front end every time after realizing the data interface, but each handwritten API document is very troublesome and reduces work efficiency. In fact, there are many frameworks that can achieve automatic generation of API documents, the most famous of which may be swagger. But swagger is a little unfriendly to windows NodeJS developers, so I gave it a try and finally chose to use apidoc to automate the generation of API documents.

Why?

Why should we use apidoc to automate and generate API documents? What advantages does it have?

Apidoc can automatically generate api documents based on comments. We just need to write comments according to apidoc syntax instead of writing markdown manually. The documents generated by apidoc are beautiful, intuitive and practical compared to markdown. If the API interface is modified or updated, you can directly modify the comments in the code.

So let's take a look at how apidoc is used. First of all, you need to install the NodeJS environment. I default that everyone has already installed the NodeJS environment.

Install apidoc dependencies

Let's first install apidoc globally using npm, with the following command:

Npm install-g apidoc

Configure apidoc

There are generally two ways to configure apidoc: create an apidoc.json file or configure it in package.json. I chose to configure it directly in package.json.

Add the configuration of apidoc at the bottom of package.json. The main configuration parameters are explained here:

Name: project name version: project version description: project introduction title: title content displayed by the browser url: interface prefix, such as http://www.niyueling.cn

The most basic configuration is completed. In the next step, we can annotate the API implementation according to the requirements of apidoc. We can first take a look at the apidoc official website documentation:

On the left are the properties we generally need to use. We can write an interface comment to see:

Let's take a look at these parameters in turn:

The @ api parameter defines the request method of the API. All my APIs are post. Let's take a look at the document's explanation of the api parameter:

Configuration file I set the interface prefix address to:

Http://www.niyueling.cn

I set the api parameter to:

@ api {POST} / users/regist user registration

Therefore, it is equivalent to that method is post and the request API:

Http://www.niyueling.cn/users/regist

The interface title is user registration.

The @ apiDescription parameter, needless to say, is the description of the interface.

The @ apiName parameter is the API interface name, and the API name cannot be duplicated.

@ apiParam can see that it is a definition parameter by looking at the name. Let's first look at the document definition:

You can see that you can set specific parameters, set length, type, value range, remarks and so on. We can analyze the account field I set above. In fact, my account field is to set the field type to string, and the remark is required for the user's mobile phone number.

The @ apiGroup parameter is actually a grouping of interfaces, such as registering and logging in APIs that belong to the user class.

The @ apiVersion parameter actually sets the version of the interface.

Of course, it is impossible for apidoc to have such simple parameters, and I do not intend to try all the parameters here, so hang up the address of the apidoc document and check it yourself if necessary:

Http://apidocjs.com/

Next, our interface comments are written in accordance with the requirements of the apidoc document, and the next step is to automatically generate the API document according to the comments. Apidoc generates documents using the command:

Apidoc-I router/-o doc

Command parsing: using the apidoc command,-I is followed by the interface folder we need to package, for example, all my interface files are placed under the router folder,-o then select the folder where we want to generate documents, and I create a new folder doc in the root path.

Done indicates that the document was generated successfully. Let's take a look at the doc folder:

You can see that a bunch of files are generated. Let's visit index.html to see the effect:

You can see that our interfaces for writing comments according to the document have all generated API documents. Is it much higher to drop a link when a customer needs a document than to drop a document? Of course, we built in the local project, if you publish the entire project server can naturally access API documents outside the network, but the local project, then the external network can not, so I chose to put the doc folder directly under the server nginx html directory, configure nginx.conf to access. First, create a new directory API under usr/share/nginx/html, and upload all files under the doc folder to the API folder:

Then configure the nginx.conf configuration file with the path:

Etc/nginx/nginx.conf

Configure the server node under http and point to API/index.html. The domain name is configured as www.niyueling.cn. After the configuration is complete, we can test whether the nginx configuration is correct. The command is:

Nginx-t

If there is no problem with the configuration, restart nginx with the command:

Nginx-s reload

Then we can visit http://www.niyueling.cn to see if we can see the API document we generated:

At this point, on the "apidoc how to achieve automatic generation of API documents" on the end of the study, I hope to be able to solve your doubts. The collocation of theory and practice can better help you learn, go and try it! If you want to continue to learn more related knowledge, please continue to follow the website, the editor will continue to work hard to bring you more practical articles!

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.