Apikit self-study diary: automatically generate API documentation

Function entry : API management application / select an item / other menus / data source synchronization (API documents are automatically generated)

This function can automatically generate API documents based on the API information of the data source by configuring the data source information.

Currently supports 5 data sources: Swagger URL, apiDoc, Github, gitlab, code cloud .

Swagger URL & apiDoc data source

The data source configuration method of Swagger URL and apiDoc is the same, you only need to fill in the source name and the access address of the json file.

• field parsing

• Source name: The name used to identify the source, inputting a name does not affect the synchronization effect.

• json file access address: Swagger URL or Json address generated by apiDoc. Note that the address must be accessible through the network, and the address must be able to return JSON-type data, otherwise it will prompt that the address cannot be accessed.

 

Gitlab & github & code cloud data source

The data source configuration of the code warehouse class is relatively complicated. The system will remotely read the code in the warehouse, and automatically generate the corresponding API document according to the code annotation format of Swagger 2.0.

• field parsing

• The data source configuration fields of each code warehouse type are parsed as follows:

GitHub

configuration item	illustrate
code repository type	Choose Github
Code warehouse address	Fill in GitHub by default: Let's build from here GitHub
username	Github account name
warehouse name	Github Repository warehouse name
access private key	Warehouse private tokens are generated in Settings->Developer settings->Personal access tokens of GitHub Repository
branch to scan	The default is the master branch, you can also choose the code branch that actually needs to be scanned
API directory path to be scanned	Storage path of API layer related code
The directory path of the data structure that needs to be scanned	Storage path of data structure-related configuration information
Target language	Java or PHP
Annotation format	The default is Swagger 2.0. For the format of code comments, refer to the following format, or refer to the official document swagger-php/Examples at 2f66ec81d2bc4b82c26b250b187d5e9ea07b0538 · zircote/swagger-php · GitHub
Data synchronization method	Currently, there are three options: incremental update, full update, and only adding new APIs. The API R&D management platform recommends incremental update. After each synchronization, the system will automatically generate the historical version of the API to facilitate rollback documents, so don't worry even if you make a mistake.
The default state for generating API documentation	The default state of the newly added API obtained by scanning, the default is the enabled state

GitLab

configuration item	illustrate
code repository type	Choose Gitlab
Code warehouse address	GitLab wired online version and users build their own private cloud version. The online version can fill in The DevSecOps Platform | GitLab . If it is GitLab deployed by yourself, write the domain name or IP port
project ID	Project IDs in GitLab
access private key	It can be obtained through the Access Tokens function of GitLab
branch to scan	The default is the master branch, you can also choose the code branch that actually needs to be scanned
API directory path to be scanned	The storage path of API layer related codes, for example: src/main/java/com/example/demo/controller
The directory path of the data structure that needs to be scanned	Storage path of data structure-related configuration information, for example: src/main/java/com/example/demo/model
Target language	Java or PHP
Annotation format	The default is Swagger 2.0. For the format of code comments, refer to the following format, or refer to the official document swagger-php/Examples at 2f66ec81d2bc4b82c26b250b187d5e9ea07b0538 · zircote/swagger-php · GitHub
Data synchronization method	Currently, there are three options: incremental update, full update, and only adding new APIs. The API R&D management platform recommends incremental update. After each synchronization, the system will automatically generate the historical version of the API to facilitate rollback documents, so don't worry even if you make a mistake.
The default state for generating API documentation	The default state of the newly added API obtained by scanning, the default is the enabled state

code cloud

configuration item	illustrate
code repository type	Choose code cloud
Code warehouse address	The access url of the project warehouse, such as Gitee - enterprise-level DevOps R&D efficiency platform
space name	The name of the space you created in Code Cloud, such as eolinker
warehouse name	The name of the warehouse in the space, such as goku
access private key	Code Cloud's Private Token
branch to scan	The default is the master branch, you can also choose the code branch that actually needs to be scanned
API directory path to be scanned	Storage path of API layer related code
The directory path of the data structure that needs to be scanned	Storage path of data structure-related configuration information
Target language	Java or PHP
Annotation format	The default is Swagger 2.0. For the format of code comments, refer to the following format, or refer to the official document swagger-php/Examples at 2f66ec81d2bc4b82c26b250b187d5e9ea07b0538 · zircote/swagger-php · GitHub
Data synchronization method	Currently, there are three options: incremental update, full update, and only adding new APIs. The API R&D management platform recommends incremental update. After each synchronization, the system will automatically generate the historical version of the API to facilitate rollback documents, so don't worry even if you make a mistake.
The default state for generating API documentation	The default state of the newly added API obtained by scanning, the default is the enabled state

sync configuration

After completing the data source configuration, you need to configure the synchronization business logic.

Data synchronization method

Supports three synchronization methods: incremental update, full update, and only adding new APIs

• Incremental update

• When updating data, judge whether the API and the content of the API have changed, and only synchronize the changed part. Such as adding new APIs and modifying changed API content. Applicable to most situations, please choose this method when you don't know how to choose to avoid data loss.

• Because incremental comparison is required, when selecting incremental update, you need to select a unique identifier for judging the API. Three methods can be selected: interface identification (operationId), interface address combined with request mode, and interface name.

• Full update

• When updating data, clear all APIs in the existing project and re-import API information from the data source. Note that this method will cause the loss of the previously edited API content, and it is only applicable to re-import all API information in a small number of cases.

• Add only new API

• When updating data, determine whether there is a new API, if there is a new API, add a new API, but will not delete the API that does not exist, and will not update the content of the existing API document.

Status Settings & New Document Grouping

No matter which data synchronization method you choose, you can configure the newly generated document status and the changed document status separately. The status option is the status of all API documents.

We can also set which group the newly generated documents are added to, and the default is the root directory.