Spring Boot Part 12: Springboot integration apidoc

First of all, apidoc generates documentation based on annotations. It is not based on any framework and supports most programming languages. For the integrity of the springboot series, it is marked with a title.

1. Introduction to apidoc

apidoc generates api documentation by commenting on your code. It is not intrusive to the code, you only need to write relevant comments, and it can generate a high-value api interface page only by writing a simple configuration. It is based on node.js, so you need to install node.js environment. Node.js installation, click here. Not introduced here.

2. Preparations

After installing node.js, install api.doc, its project source code: https://github.com/apidoc/apidoc .

Install by command:

npm install apidoc -g

3. How to write notes

@api

@api {method} path [title]

method：请求方法，
path：请求路径 
title(可选)：标题

@apiDescription

@apiDescription text
text说明

@apiError

@apiError [(group)] [{type}] field [description]

（group）（可选）：参数将以这个名称分组，不设置的话，默认是Error 4xx 
{type}（可选）：返回值类型，例如：{Boolean}, {Number}, {String}, {Object}, {String[]} 
field：返回值字段名称 
descriptionoptional（可选）：返回值字段说明

@apiGroup

@apiGroup name
name：组名称，也是导航的标题

For more comments, see the official documentation: http://apidocjs.com/#params

Fourth, write to chestnuts

First write the configuration file

Create a new apidoc.json file in the main directory of the project:

{
  "name": "example",
  "version": "0.1.0",
  "description": "A basic apiDoc example"
}

More configuration reference: http://apidocjs.com/#configuration

Write a note:

    /**
     * @api {POST} /register 注册用户
     * @apiGroup Users
     * @apiVersion 0.0.1
     * @apiDescription 用于注册用户
     * @apiParam {String} account 用户账户名
     * @apiParam {String} password 密码
     * @apiParam {String} mobile 手机号
     * @apiParam {int} vip = 0  是否注册Vip身份 0 普通用户 1 Vip用户
     * @apiParam {String} [recommend] 邀请码
     * @apiParamExample {json} 请求样例：
     *                ?account=sodlinken&password=11223344&mobile=13739554137&vip=0&recommend=
     * @apiSuccess (200) {String} msg 信息
     * @apiSuccess (200) {int} code 0 代表无错误 1代表有错误
     * @apiSuccessExample {json} 返回样例:
     *                {"code":"0","msg":"注册成功"}
     */

Generate documentation interface with apidoc command

First cd to the outer directory of the project, and create a directory for outputting documents in the outer directory. I built docapi.

Enter command:

apidoc -i chapter4/ -o apidoc/

-i input directory -o output directory

chapter4 is my project name.

You can see that many files are generated in the apidoc directory:

Open index.html, you can see the documentation page:

5. References

apidoc

apidocjs.com

Use apidoc to generate Restful web Api documentation