个人博客同步文章https://mr-houzi.com/2018/07/...apidoc是一个使用源代码注释创建RESTfulWebAPI文档的工具。apidoc可用于C#、Go、Dart、Java、JavaScript、PHP、TypeScript和所有其他支持Javadoc的语言。安装npminstallapidoc-g运行apidoc-imyapp/-oapidoc/-tmytemplate/myapp/根据myapp文件夹下文件的注释创建文件apidoc/文件输出位置mytemplate/使用模板命令line界面查看帮助，用于显示命令行参数：apidoc-hconfiguration(apidoc.json)apidoc.json中配置项目的基本信息{"name":"example","version":"0.1.0","description":"apiDocbasicexample","title":"自定义apiDoc浏览器标题","url":"https://api.github.com/v1"}apidoc也支持通过package.json设置，只需添加“apidoc”：在{}下添加参数。{"name":"example","version":"0.1.0","description":"apiDocbasicexample","apidoc":{"title":"自定义apiDoc浏览器标题","url":"https://api.github.com/v1"}}如果要设置页眉和页脚，请将以下信息添加到apidoc.json（不要忘记创建markdown文件）。{"header":{"title":"我自己的页眉标题","filename":"header.md"},"footer":{"title":"我自己的页脚标题","filename":"footer.md"}}使用接下来介绍常用的参数。完整的介绍可以自行阅读官方文档。一般情况下，以下就够了。@api@api{method}path[title]声明请求方法、请求路径等名称描述method请求方法：DELETE,GET,POST,PUT,...pathrequestpathtitle简称。(用于导航和文章标题)eg:/***@api{get}/user/:id*/@apiDeprecated@apiDeprecated[text]将API方法标记为已弃用方法。Namedescriptiontexttextdescription@apiName@apiNamename定义方法文档块的名称。该名称将用于生成的输出中的子导航。结构定义不需要@apiName。name描述了name方法的唯一名称。
格式：方法+路径（如Get+User），建议这样命名eg:/***@api{get}/user/:id*@apiNameGetUser*/@apiGroup@apiGroup名称定义方法文档块属于哪个组。组将用于生成的输出中的主要导航。例如：登录和注册界面都可以分配给用户组。name描述组名的名称。也用作导航标题。eg:/***@api{get}/user/:id*@apiGroupUser*/@apiHeader@apiHeader[(group)][{type}][field=defaultValue][description]描述传递的API-Header参数，例如授权。名称描述组参数组类型参数类型字段参数名称描述eg:/***@api{get}/user/:id*@apiHeader{String}access-key用户唯一的access-key。*/@apiParam@apiParam[(group)][{type}][field=defaultValue][description]用于描述API参数值名称描述组参数组类型参数类型字段参数名称描述eg:/**@apiParam(params){int}time时间戳（用于判断请求是否超时）*@apiParam(params){String}token确认访客身份*@apiParam(params){String}user_name电话号码或邮箱*@apiParam(params){String}user_pwdMD5加密用户密码*/@apiSuccess@apiSuccess[(group)][{type}]field[description]成功返回参数。用法类似于@apiParam。个人觉得@apiSuccess有点多余，用@apiSuccessExample就够了。@apiSuccessExample@apiSuccessExample[{type}][title]example成功返回消息的示例，输出为预格式化代码。例如：/***@api{get}/user/:id*@apiSuccessExample{json}成功响应：*HTTP/1.1200OK*{*"firstname":"John",*"lastname":"Doe"*}*/@apiError错误返回参数。用法类似于@apiSuccess@apiErrorExample错误返回信息的例子，输出为预先格式化的代码。用法类似于@apiSuccessExample。@apiVersion@apiVersionversion设置文档块的版本。版本也可用于@apiDefine。例如：/***@api{get}/user/:id*@apiVersion1.6.2*/@apiIgnore@apiIgnore[提示]把它放在块的顶部。@apiIgnore将无法解析该块。如果您在源代码中留下过时或未完成的方法并且不想在文档中发布它们，这将很有用。名称描述提示用于提示忽略此块的原因。eg:/***@apiIgnoreNotfinishedMethod*@api{get}/user/:id*/给一个完整的例子举个栗子/***@api{post}/user/login用户登录*@apiName登录*@apiGroupUser*@apiParam(params){int}时间戳（用于判断请求是否超时）*@apiParam(params){String}token确认访问者身份*@apiParam(params){String}user_name手机ID或邮箱*@apiParam(params){String}user_pwdMD5加密用户密码*@apiSuccessExampleSuccess-Response:*{*"code":200,*"msg":"登录成功！",*"data":{*'uid':1,//用户ID*'user_phone':'13011111111',//用户电话号码*'user_nickname':'小明',//用户昵称*'user_email':'123456789@163.com',//用户邮箱*'user_rtime':1501414343//用户注册时间*}**/效果：
