How to use eolinker to scan GitLab code comments to automatically generate API documentation?

Time:2019-10-23

Preface:

After you’ve written your code, write all kinds of parameter annotations into the API documentation to facilitate subsequent docking and testing. This process is usually cumbersome, and it would be very convenient if you had a tool that could read the code annotations and directly generate the API documentation.
I’ve been using eolinker all my life, but I’ve been living in a hell of a lot of trouble since their annotation-generated documentation feature went offline last year — I really don’t want to write documents, I’m really tired.
However after these two days of line, discover this function to go online again suddenly! Must give everyone a wave amway!
Official website: https://www.eolinker.com
According to the official explanation, this function is simply to read the PHP code of gitlab (which should still be able to read local code before) (until the post added support for reading Java, which is more convenient), comment and generate API documents.

The following is the official operation description:

1. Create a new project in EOLINKER, and then enter the project profile page, where you can find the “scan code annotation to generate document” module.

How to use eolinker to scan GitLab code comments to automatically generate API documentation?

2. Before synchronizing, we turn on the Settings to see what information we need to fill in.

How to use eolinker to scan GitLab code comments to automatically generate API documentation?

There are 10 choices, let’s see how to fill in:

  • 1. Code repository type, now only gitlab by default, asked their PM in the official group, github should be supported later.
  • 2. Address of the code warehouse, the online version of gitlab and the private cloud version built by users themselves. The online version can be filled in https://gitlab.com.
  • 3. Project ID. There will be a project ID after a new project is created in gitlab.
  • 4. Access the private key, which can be acquired with the Access Tokens function of gitlab, as detailed below.
  • 5. The branch to be scanned is master by default. We can also create a new branch.
  • 6. Need to scan API directory path, create a directory as API directory.
  • 7. Need to scan the directory path of data structure, and establish a directory as the directory of data structure.
  • 8. The target language is only PHP by default at present. Unfortunately, there is only one language.
  • 9. Annotation format, defaults to Swagger, 2.0 code comments written format can be in accordance with the following form to write, or official documents http://zircote.com/swagger-ph…

Such as the model of

How to use eolinker to scan GitLab code comments to automatically generate API documentation?

Such as the controller of the

How to use eolinker to scan GitLab code comments to automatically generate API documentation?

  • 10. Data synchronization mode, currently optionalIncremental updates, full updates, and only new AP’sI has three forms. That’s all you need to fill out. To fill in this information correctly, we then go to gitlab for setup.

Since Gitlab has not been officially introduced, it would be appropriate for me to introduce it first: Gitlab is an open source project for a repository management system, which USES git as a code management tool and builds a web service based on it. Gitlab is similar to github in that it is both a web-based git repository. I won’t go into the details of how to register a new gitlab account, but if you already have a github account, you can log in to gitlab with github account.

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

How to use eolinker to scan GitLab code comments to automatically generate API documentation?

How to use eolinker to scan GitLab code comments to automatically generate API documentation?

2. Create a new branch of the master and create two new directories under it: controllers and models, one for the API directory and one for the data structure directory.

How to use eolinker to scan GitLab code comments to automatically generate API documentation?

3. Upload the written PHP code to the respective directory. You can use the command line or upload files directly.

How to use eolinker to scan GitLab code comments to automatically generate API documentation?

How to use eolinker to scan GitLab code comments to automatically generate API documentation?

4. After successfully uploading the code, the key is obtained. In gitlab, you need the Access Tokens function to generate keys. Enter the Settings page and enter the corresponding project name through the Access Tokens function in the menu on the left. Check open permissions as needed. If you don’t understand them, check them as shown in the screenshot below. The diagram below:

How to use eolinker to scan GitLab code comments to automatically generate API documentation?

How to use eolinker to scan GitLab code comments to automatically generate API documentation?

5. Up to this point, we have got all the information, and then go back to EOLINKER to fill in the information. Please see the figure below.

How to use eolinker to scan GitLab code comments to automatically generate API documentation?

So why would I choose incremental update? What is the difference between the three kinds of synchronous update?

  • Incremental update: determine the details of the existing API and add new API information. Replace existing data with annotated data. Data that is not partially annotated, such as mocks, parameter value possibilities, detailed documentation, and so on, is preserved.
  • Full update: on the basis of adding new API, full replacement of the information in the existing API, according to the annotation, do not retain the data without annotation.
  • Add only new apis: determine if the interface name already exists and insert if it does not.

Sounds confusing. Let’s take an example. The interface on Gitlab has only parameters, while the EOLINKER is imported with mock, detailed documentation, and other data. Suppose your gitlab repository now has ABCD four interface data and A one interface data in EOLINKER.

Here is an example of the difference between the three types of data synchronous update. The interface in GitLab only has parameters, while the imported EOLINKER has mock, detailed documentation and other data. Suppose your GitLab warehouse now has four ABCD interfaces and one A interface in EOLINKER.

  • With incremental update, three new BCD interfaces will be added to EOLINKER; If the data of the warehouse A interface is updated, the mock and detailed document data of the original local A interface will be maintained at the same time.
  • With full update, EOLINKER will have four ABCD interfaces. At this time, all the data of the local A interface is not retained, but consistent with the data of the A interface in the warehouse.
  • After adopting “add new API only”, EOLINKER will judge whether to add new API by interface name, so EOLINKER will add three new BCD interfaces. Even if the parameters on GitLab have changed, the local original A interface data remains unchanged.

Therefore, incremental updates are recommended regardless of the situation. But even if you do, EOLINKER automatically generates an API history so we can roll back the document.

1. According to the official instructions, the document will start to be synchronized immediately after the Settings are completed and the time required for synchronizing the document will be determined according to the amount of data in the code comments.

How to use eolinker to scan GitLab code comments to automatically generate API documentation?

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

How to use eolinker to scan GitLab code comments to automatically generate API documentation?

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

How to use eolinker to scan GitLab code comments to automatically generate API documentation?

One more thing: according to their update speed, they have already supported reading Java code on gitlab. The operation steps are similar to those of reading PHP.

conclusion

If you can automatically generate API documents by scanning code comments, you won’t have to write interface documents one by one after writing code annotations. Now there’s another reason to stop using swagger. This new feature can reduce most of the unnecessary work. Although it can only support the PHP code and Java code on gitlab, it will definitely continue to support more platform and programming language codes in the future. It will be more convenient and fast to use continuously. Official website: https://www.eolinker.com