Web API document generation tool apidoc

Original address: Liang Guizhao’s blog

In the process of server-side development, we need to provide an API interface document for the Use of Web and mobile terminals. There are many ways to document an API, such as through a Word document or through MediaWiki maintenance. Another popular way to automate document generation is to use Swagger. Here, I would like to share another Web API document generation tool, Apidoc.

Apidoc generates Web API documentation from annotations in the source code. Therefore, APIDOC can be non-invasive to existing code. Apidoc supports C#, Go, Dart, Java, JavaScript, PHP, TypeScript, CoffeeScript, Erlang, Perl, Python, Ruby, Lua. Apidoc makes it very easy to generate interactive document pages.

Great start

First, we need Node.js support. After setting up the Node. js environment, enter the NPM name on the terminal to install it.

npm install apidoc -g
Copy the code

Next, we need to add the apidoc.json file to the project root directory.

{
  "name": "example"."version": "0.1.0 from"."description": "apiDoc basic example"."title": "Custom apiDoc browser title"."url" : "https://api.github.com/v1"
}
Copy the code

Here, I focus on demonstrating how Java annotations can be used in conjunction with APidOC. Now, let’s take a look at a case.

/** * @api {GET} Logistics /policys * @apidescription QUERY early warning policy * @apigroup QUERY * @apiname Logistics /policys * @APIParam {Integer} Edition Platform type * @APIParam {String} tenantCode Merchant name * @APIPermission LOGISTICS_POCILY */Copy the code

Finally, we input apidoc command on the terminal for document generation. Here, we replace myapp/ with the root of our project and apidoc/ with the address where the document needs to be generated.

apidoc -i myapp/ -o apidoc/ 
Copy the code

For example, the author’s configuration looks like this.

apidoc -i /Users/lianggzone/Documents/dev-space/git-repo -o /Users/lianggzone/Documents/dev-space/apidoc/ 
Copy the code

Code comments

@api

The @API tag is mandatory, and only comment blocks using the @API tag will be parsed to produce document content. The format is as follows:

@api {method} path [title]
Copy the code

Here, it is necessary to explain the parameters.

@apiDescription

@apidescription Describes the API. The format is as follows:

@apiDescription text
Copy the code

@apiGroup

@apigroup represents the group name, which is resolved into a navigation bar menu. The format is as follows:

@apiGroup name
Copy the code

@apiName

@apiname Indicates the interface name. Note that @apis with the same name are distinguished by @apiVersion under the same @apigroup, otherwise the @API will override the @API defined earlier. The format is as follows:

@apiName name
Copy the code

@apiVersion

@apiVersion Indicates the version of the interface and is used together with @apiname. The format is as follows:

@apiVersion version
Copy the code

@apiParam

@apiParam Defines the request parameters required by the API interface. The format is as follows:

@apiParam [(group)] [{type}] [field=defaultValue] [description]
Copy the code

Here, it is necessary to explain the parameters.

Similarly, @apiHeader defines the request headers required by the API interface, @apisuccess defines the response success required by the API interface, and @APIError defines the response error required by the API interface.

Here, let’s look at an example.

/** * @APIParam {Integer} edition=1 Platform type * @APIParam {String} [tenantCode] Merchant name */Copy the code

In addition, @ApiParamExample, @ApiHeaderExample, @ApierRorexample, and @apisucCessexample can be used to provide examples in your documentation.

@apiPermission

@apiPermission Defines the permission points required by the API interface. The format is as follows:

@apiPermission name
Copy the code

In addition, there are some special notes. For example, @apideprecated indicates that the API interface is obsolete, and @apiIgnore indicates that the interface resolution is ignored. For more details, read the official documentation: http://apidocjs.com/#demo

Complete case

Finally, we use the official case to explain the next complete configuration.

First, configure apidoc.json as follows:

{
  "name": "example"."version": "0.1.0 from"."description": "A basic apiDoc example"
}
Copy the code

Next, we configure the associated Java source annotations.

/** * @api {get} /user/:id Request User information * @apiName GetUser * @apiGroup User * * @apiParam {Number} id Users unique ID. * * @apiSuccess {String} firstname Firstname of the User. * @apiSuccess {String} lastname Lastname of the User. * * @apisuccessexample Success-Response: * HTTP/1.1 200 OK * {*"firstname": "John",
 *       "lastname": "Doe"* } * * @apiError UserNotFound The id of the User was not found. * * @apiErrorExample Error-Response: * HTTP/1.1 404 Not Found * {*"error": "UserNotFound"
 *     }
 */
Copy the code

Then, perform the naming to generate the document.

apidoc -i myapp/ -o apidoc/
Copy the code

The generated page is shown below.

(after)

More wonderful articles, all in the “server-side thinking” wechat public account!