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

This article is to share with you about still using eolinker to scan GitLab code comments automatically, the editor thinks it is very practical, so I share it with you to learn, I hope you can get something after reading this article, not to say much, follow the editor to have a look.

Foreword:

Generally, after writing the code, you have to write all kinds of parameter comments into the API document to facilitate subsequent docking and testing. This process is usually very troublesome, and it will be very convenient if there is a tool that can read the code comments and generate the API document directly.

I've been using eolinker all the time, but I've been living a hard time since their "comment-generating documentation" feature went offline last year-I really don't want to write documents. I'm really tired.

However, after being online these two days, I suddenly found that this function was back online! We must give everyone a wave of Amway!

According to the official explanation, this function is simply to read gitlab (previously should be able to read native code) php code (as of the post added support for reading java, more convenient) comments to generate API documents.

The following is an official introduction to the operation:

1. First create a new project in EOLINKER, and then go to the project overview page, where you can find the "scan code comments generate documentation" module.

two。 Before synchronizing, let's open the settings and see what information we need to fill in.

There are a total of 10 options. Let's take a look at how to fill in:

1. Code repository type, now only gitlab by default, in the official group asked their PM, should also support github later.

two。 Code repository address, gitlab online version and user-built private cloud version. You can enter https://gitlab.com in the online version. If you deploy gitlab, write the domain name or IP port.

3. After the new project is created in the project ID,gitlab, there will be a project ID. Just enter it.

4. The access private key can be obtained through the Access Tokens feature of gitlab. How to obtain it will be described in detail later.

5. The branch to be scanned. Default is master. We can also create a new branch.

6. You need to scan the API directory path and create a directory as the API directory.

7. The directory path of the data structure needs to be scanned and a directory is established as the data structure directory.

8. At present, the target language is only PHP by default, but it is a pity that there is only one language, but I chatted with their customer service and said that the later updated language support would add java.

9. The format of annotations is Swagger 2.0by default. The format of code comments can be written as follows, or refer to the official document http://zircote.com/swagger-php/annotations.html.

Like model's.

Like controller's.

10. Data synchronization method, currently available incremental update, full update, only add new API three forms. The above is all the information you need to fill in. To fill in this information correctly, next we need to go to gitlab to set it up.

Since there is no official introduction to Gitlab, it is appropriate for me to introduce it first: gitLab is an open source project for warehouse management system, which uses git as a code management tool and builds web services on this basis. Gitlab is similar to github in that it is based on web's git repository. I won't say much about how to register a new gitlab account, but if you already have an github account, you can log in to gitLab with your github account.

1. The first step is to create a new project. Here I have created a new project called demo code.

two。 After the new creation, there is already a branch of master, and then two new directories are created under the branch: I named them controllers and models, one as the API directory path and the other as the data structure directory path.

3. Upload the written php code to a separate directory. You can use the command line directly or upload the file directly.

4. After successfully uploading the code, the key is obtained. In gitlab, the Access Tokens function is required to generate keys. First go to the settings page, fill in the corresponding project name through the Access Tokens function in the left menu, and then check the open permissions as needed. If you don't understand, you can check it according to my screenshot below. Click on the green box and you can get the personal key. As shown below:

5. At this step, we have got all the information, and then go back to EOLINKER to fill in the information, please see the following figure, notice that the data synchronization method I choose is incremental update.

Then why did I choose incremental updates? What is the difference between the three kinds of data synchronous updates?

Incremental update: determine the details of the existing API and add new API information. Replace existing data with annotated data. Data that is not available in some of the annotations, such as mock, parameter value possibilities, detailed documentation, and so on, will be retained.

Full update: on the basis of adding a new API, completely replace the information in the existing API, subject to the annotations, and do not retain the data that is not available in the annotations.

Only add a new API: determine whether the interface name already exists, or insert if it does not exist.

It sounds very round. let's give an example. The interface on Gitlab has only parameters, and there will be mock, detailed documents and other data after importing EOLINKER. Suppose you have ABCD four interface data in your gitlab warehouse and An interface data in EOLINKER.

The following example shows the difference between the following three kinds of data synchronization updates. The interfaces in GitLab only have parameters, while there will be mock, detailed documents and other data after importing EOLINKER. Suppose you have four ABCD interfaces in your GitLab warehouse and one interface An in EOLINKER.

After adopting "incremental update", three new BCD interfaces will be added to the EOLINKER. If the data of the warehouse An interface is updated, the local updated data will be added while keeping the mock and detailed document data of the original local An interface.

After "full update" is adopted, there will be four ABCD interfaces on the EOLINKER. In this case, all data of the local An interface will not be retained, but will be consistent with the data of the An interface in the warehouse.

When "only add new API" is adopted, EOLINKER will use the interface name to determine whether a new API needs to be added, so three new BCD interfaces will be added to the EOLINKER. Even if the parameters on the GitLab have changed, the data of the local An interface will remain unchanged.

Therefore, incremental updates are recommended in any case. However, even if you still misoperate, EOLINKER will automatically generate a historical version of API, making it easy for us to roll back the document.

1. According to the official instructions, the document will begin to synchronize immediately after the setup is completed, and the time required to synchronize the document will be determined by the amount of data commented in the code.

The 2.API document and the corresponding grouping are automatically generated, as shown in the following figure.

3. Then we can edit and modify the document directly, which is much more convenient.

If you can automatically generate API documents by scanning code comments, you don't have to write interface documents one by one after writing code comments, and now there's another reason not to use swagger.

The above is that we will still use eolinker to scan GitLab code comments automatically. The editor believes that there are some knowledge points that we may see or use in our daily work. I hope you can learn more from this article. For more details, please follow the industry information channel.

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.