SpringBoot-(2)安装和使用apidoc生成接口文档

apidoc的安装和使用

前言

apidoc能做什么

apidoc是一个轻量级的在线REST接口文档生成系统，可以根据其特定的规则的代码注释来生成静态网页。首先看下它生成的文档界面和风格。

1、安装

1 node的安装

首先，去node.js官网上下载最新的安装包，请下载自己对应系统的安装包。譬如笔者的操作系统是64位Windows操作系统，就下载下图所示的node安装包。

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-0O6R3c8d-1602557534834)(https://raw.githubusercontent.com/188xuhe/images/master/image-20201012173542412.png?token=AIFEVYFQIPQIJYVFQGZ6SAS7QQS7U)]

npm（node package manager，node安装包管理器）也是很重要的，可以通过它来便捷地下载和安装node应用。在Windows Shell中输入npm命令，如果出现如下图所示的信息，则表示npm也正确安装完毕。

2 apidoc安装

apidoc可以利用npm来快速安装。

npm install apidoc -g

输入apidoc -v命令，如果出现如下图所示的界面，则表示apidoc已安装成功。

apidoc -v

2、使用

1 在需要生成api接口文档的项目下添加apidoc.json文件

apidoc.json

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

2 生成api文档

apidoc -i demo/ -o demo/doc
apidoc -i 项目地址 -o 生成的文档地址

3 api文档

最终的api文档为：

3、注释详解

1 @api

必要的，

@api {method} path [title]

Name	Description
method	Request method name: DELETE, GET, POST, PUT
path	Request Path.
title optional	A short title. (used for navigation and article header)

Example:

/**
 * @api {get} /user/:id
 */

2 @apiDescription

API方法的详细描述

@apiDescription text

Name	Description
text	Multiline description text.

Example:

/**
 * @apiDescription This is the Description.
 * It is multiline capable.
 *
 * Last line of Description.
 */

3 @apiError

返回参数错误。

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

Name	Description
(group)optional	All parameters will be grouped by this name. Without a group, the default Error 4xx is set. You can set a title and description with @apiDefine.
{type}optional	Return type, e.g. {Boolean}, {Number}, {String}, {Object}, {String[]} (array of strings), …
field	Return Identifier (returned error code).
descriptionoptional	Description of the field.

Example:

/**
 * @api {get} /user/:id
 * @apiError UserNotFound The <code>id</code> of the User was not found.
 */

4 @apiErrorExample

一个错误返回消息的例子，输出为预格式化的代码。

@apiErrorExample [{type}] [title]
                 example

Name	Description
typeoptional	Response format.
titleoptional	Short title for the example.
example	Detailed example, multilines capable.

Example:

/**
 * @api {get} /user/:id
 * @apiErrorExample {json} Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

5 @apiExample

API方法的使用示例。输出为预先格式化的代码。

@apiExample [{type}] title
            example

Name	Description
typeoptional	Code language.
title	Short title for the example.
example	Detailed example, multilines capable.

Example:

/**
 * @api {get} /user/:id
 * @apiExample {curl} Example usage:
 *     curl -i http://localhost/user/4711
 */

6 @apiGroup

应该一直使用。定义方法文档块属于哪个组。组将用于生成的输出中的主导航。

Name	Description
name	Name of the group. Also used as navigation title.

Example:

/**
 * @api {get} /user/:id
 * @apiGroup User
 */

7 @apiHeader

描述传递给api头的参数，例如用于授权。

@apiHeader [(group)] [{type}] [field=defaultValue] [description]

Name	Description
(group)optional	All parameters will be grouped by this name. Without a group, the default Parameter is set. You can set a title and description with @apiDefine.
{type}optional	Parameter type, e.g. {Boolean}, {Number}, {String}, {Object}, {String[]} (array of strings), …
field	Variablename.
[field]=defaultValueoptional	Fieldname with brackets define the Variable as optional.
descriptionoptional	Description of the field.

Examples:

/**
 * @api {get} /user/:id
 * @apiHeader {String} access-key Users unique access-key.
 */

8 @apiHeaderExample

@apiHeaderExample [{type}] [title]
                   example

Name	Description
typeoptional	Request format.
titleoptional	Short title for the example.
example	Detailed example, multilines capable.

Example:

/**
 * @api {get} /user/:id
 * @apiHeaderExample {json} Header-Example:
 *     {
 *       "Accept-Encoding": "Accept-Encoding: gzip, deflate"
 *     }
 */

9 @apiIgnore

带有@apiIgnore的块将不会被解析。如果您在源代码中保留了过时的或未完成的方法，并且不想将其发布到文档中，那么它是很有用的。

@apiIgnore [hint]

Name	Description
hintoptional	Short information why this block should be ignored.

Example:

/**
 * @apiIgnore Not finished Method
 * @api {get} /user/:id
 */

10 @apiName

应该一直使用。

定义方法文档块的名称。名称将用于生成的输出中的子导航。结构定义不需要@apiName。

@apiName name

Name	Description
name	Unique name of the method. Same name with different @apiVersion can be defined.

Example:

/**
 * @api {get} /user/:id
 * @apiName GetUser
 */

11 @apiParam

描述一个传递给api方法的参数。

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

Name	Description
(group)optional	All parameters will be grouped by this name. Without a group, the default Parameter is set. You can set a title and description with @apiDefine.
{type}optional	Parameter type, e.g. {Boolean}, {Number}, {String}, {Object}, {String[]} (array of strings), …
{type{size}}optional	Information about the size of the variable. {string{..5}} a string that has max 5 chars. {string{2..5}} a string that has min. 2 chars and max 5 chars. {number{100-999}} a number between 100 and 999.
{type=allowedValues}optional	Information about allowed values of the variable. {string="small"} a string that can only contain the word “small” (a constant). {string="small","huge"} a string that can contain the words “small” or “huge”. {number=1,2,3,99} a number with allowed values of 1, 2, 3 and 99. Can be combined with size: {string {..5}="small","huge"} a string that has max 5 chars and only contain the words “small” or “huge”.
field	Fieldname.
descriptionoptional	Description of the field.

Examples:

/**
 * @api {get} /user/:id
 * @apiParam {Number} id Users unique ID.
 */

/**
 * @api {post} /user/
 * @apiParam {String} [firstname]       Optional Firstname of the User.
 * @apiParam {String} lastname          Mandatory Lastname.
 * @apiParam {String} country="DE"      Mandatory with default value "DE".
 * @apiParam {Number} [age=18]          Optional Age with default 18.
 *
 * @apiParam (Login) {String} pass      Only logged in users can post this.
 *                                      In generated documentation a separate
 *                                      "Login" Block will be generated.
 *
 * @apiParam {Object} [address]         Optional nested address object.
 * @apiParam {String} [address[street]] Optional street and number.
 * @apiParam {String} [address[zip]]    Optional zip code.
 * @apiParam {String} [address[city]]   Optional city.
 */

12 @apiParamExample

@apiParamExample [{type}] [title]
                   example

Name	Description
typeoptional	Request format.
titleoptional	Short title for the example.
example	Detailed example, multilines capable.

Example:

/**
 * @api {get} /user/:id
 * @apiParamExample {json} Request-Example:
 *     {
 *       "id": 4711
 *     }
 */

13 @apiSuccess

成功返回参数。

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

Name	Description
(group)optional	All parameters will be grouped by this name. Without a group, the default Success 200 is set. You can set a title and description with @apiDefine.
{type}optional	Return type, e.g. {Boolean}, {Number}, {String}, {Object}, {String[]} (array of strings), …
field	Return Identifier (returned success code).
descriptionoptional	Description of the field.

Example with Array:

/**
 * @api {get} /users
 * @apiSuccess {Object[]} profiles       List of user profiles.
 * @apiSuccess {Number}   profiles.age   Users age.
 * @apiSuccess {String}   profiles.image Avatar-Image.
 */

14 @apiSuccessExample

@apiSuccessExample [{type}] [title]
                   example

Example:

/**
 * @api {get} /user/:id
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 */

15 @apiUse

@apiUse name

与@apiDefine共用

Example:

/**
 * @apiDefine MySuccess
 * @apiSuccess {string} firstname The users firstname.
 * @apiSuccess {number} age The users age.
 */

/**
 * @api {get} /user/:id
 * @apiUse MySuccess
 */

16 @apiVersion

@apiVersion version

Example:

/**
 * @api {get} /user/:id
 * @apiVersion 1.6.2
 */

tips：详细参见