Preface:

Generally, after writing the code, you need to write all kinds of parameter annotations into the API document for subsequent docking and testing. This process is often cumbersome, but it would be very convenient if a tool could read the code comments and generate the API document directly. I’ve been using Eolinker all my life, but since their “comment to document” function went offline last year, I’ve been living in a world of misery – I really don’t want to write documents, I’m really tired. However, two days after the line, suddenly found that this function is online again! Must give everyone an amicable wave! According to the official explanation, this function simply reads the PHP code of GitLab (should also be able to read local code) (until the post added support for reading Java, more convenient) to generate API documentation.

Here is the official operation introduction:

1. First create a new project in EOLINKER, then go to the project overview page, where you can find the module “Scan code annotations to generate documents”.

2. Before synchronization, let’s open the Settings to see what information needs to be filled in.

There are a total of 10 choices. Let’s see how to fill in each one:

  • 1. The repository type, now the default is only GitLab, asked their PM in the official group, should also support Github later.
  • 2. Code warehouse address, gitlab wired version and user built private cloud version, online version can be filled in https://gitlab.com, if the deployment of gitLab write domain name or IP port.
  • 3. Project ID. After a new project is created in GitLab, there will be a project ID.
  • 4. Access private keys, which are available through gITLab’s Access Tokens feature. More on how to Access these Tokens later.
  • 5. The branch to be scanned is master by default. We can also create a new branch.
  • 6. API directory path to be scanned. Create a directory as the API directory.
  • 7. Path of the data structure directory to be scanned. Create a directory as the data structure directory.
  • 8. The target language is currently only PHP by default, but it is a pity that there is only one language, but I talked to their customer service and said that Java will be added in the updated language support.
  • 9. Annotation format, defaults to Swagger, 2.0 code comments written format can be in accordance with the following form to write, or refer to the official documentation at http://zircote.com/swagger-php/annotations.html

Such as the model of

Such as the controller of the

  • 10. Data synchronization mode: Currently, incremental update, full update and only new API can be selected. That’s all the information you need to fill in. To fill in this information correctly, we then go to GitLab to set it up.

GITLAB

Gitlab is an open source project for a warehouse management system that uses Git as a code management tool and builds a Web service based on it. Gitlab is similar to Github, which is a web-based Git repository. I won’t go into details about how to register a gitlab account, but if you already have a Github account, you can log in to Gitlab with a Github account.

1. First, I need to create a new project. Here I created a project named Demo code.

Create two new directories under the branch named Controllers and models, one for the API directory and one for the data structure directory.

3. Upload the WRITTEN PHP code to the respective directories. You can upload files directly from the command line or directly.

4. After successfully uploading the code, the key is obtained. In GITLab, generating keys requires the Access Tokens function. First go to the setup page, use the Access Tokens function in the menu on the left, and fill in the corresponding project name. Then check the open Tokens as required. If you don’t understand them, you can check them according to my screenshot below. The diagram below:

5. At this point, we have all the information, go back to EOLINKER and fill in the information, see the picture below, note that I chose incremental update for data synchronization.

So why did I choose incremental updates? What are the differences between the three types of synchronous updates?

  • Incremental update: Identifies details about existing apis and adds new API information. Replace existing data with annotated data. Data that is not present in some annotations, such as mocks, parameter value possibilities, detailed documentation, and so on, is retained.
  • Full update: On the basis of adding a new API, completely replace the information in the existing API, using the annotations as the criterion, do not retain the data that is not in the annotations.
  • Add only new API: Check whether the interface name already exists or insert it if it does not.

Here is an example to illustrate the differences between the three types of data synchronization updates. GitLab interfaces only have parameters, while EOLINKER imports mock, detailed documents, and other data. Suppose your GitLab repository now has four ABCD interfaces and one EOLINKER interface.

  • After incremental Update, three BCD interfaces are added to EOLINKER. If the data of the warehouse A interface is updated, the mock and detailed document data of the local A interface will be kept, and the corresponding updated data will be added locally.
  • After full Update is adopted, EOLINKER has four ABCD interfaces. In this case, all data of the local interface A is not retained, but is consistent with the data of interface A in the warehouse.
  • After Add New API only is selected, EOLINKER determines whether to add new apis based on interface names. Therefore, three BCD interfaces are added to EOLINKER. Even if the parameters on GitLab have been changed, the local original A interface data remains unchanged.

Therefore, incremental updates are recommended in any case. But if you still make a mistake, EOLINKER will automatically generate a history of the API so that we can roll back the document.

1. According to the official instructions, the document will start to synchronize after the setting is completed and click Sync Now, and the time required to generate the document will be determined by the amount of data in the code comments.

2.API documents and corresponding groups are automatically generated, as shown below.

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

Add: according to their update speed, currently also support to read Java code on GitLab, the operation steps are similar to read PHP steps, here will not expand to say, do not know, please go back to read the article HHH.

conclusion

If you can automatically generate API documentation by scanning code comments so that you don’t have to write interface documentation line by line after code comments are written, there’s another reason to stop using Swagger. This new function can reduce most of the unnecessary workload. Although it can only support PHP code and Java code on GitLab now, it will definitely continue to support more platforms and programming language codes in the future, which will be more convenient and fast to use continuously. I hope Eolinker can bring us more surprises. Official website: www.eolinker.com