标签：String title ApiDoc 接口 js api 文档 apiSuccess apidoc
前端和后端注释文档生成
前端和后端的 函数及api 说明文档生成总结，持续更新中 by Qzx
参考网址
apiDoc的使用教程
一、安装
# 全局安装
npm install apidoc -g
# 查看是否安装成功,显示命令行参数
apidoc -h
二、apidoc 常用命令说明
| 指令简写 | 指令全称 | 说明 |
|---|---|---|
| -f | --file-filters | 过滤器，指定应该解析的文件类型，后缀 （可以使用多个-f）。默认.cs .dart .erl .go .java .js .php .py .rb .ts。示例（仅解析.js和.ts文件）：apidoc -f ".*\.js" -f ".*\\.ts" |
| -e | --exclude-filters | 过滤器用于选择不应该解析的文件 |
| -i | --input | 指定输入的源目录名，项目文件的位置，默认为 ./ 例：apidoc -i myapp/ |
| -o | --output | 指定输出的目录文件名，放置生成文档的位置，默认为 ./doc/，例：apidoc -o apidoc/ |
| -t | --template | 指定要用的外部模板的路径，可以创建和使用自己的模板，默认使用全局的 node_modules/apidoc/template/ ，例：apidoc -t mytemplate/ |
| -c | --config | 指定配置文件的路径 apidoc.json ./ |
| -h | --help | 显示详细的帮助说明 |
| --debug | --debug | 显示调试的信息，默认为 false |
三、具体使用
-
在项目文件夹新建apidoc.json;
-
在项目目录运行：
apidoc -i myapp/ -o apidoc/ -t mytemplate/ # 简写指令 apidoc
说明：上面的指令可以直接简写为 apidoc，没有任何参数时，默认从当前目录(包括子目录)下格式为(.cs .dart .erl .go .java .js .php .py .rb .ts) 的所有文件生成文档并将输出写入 ./doc/。
四、基本配置（apidoc.json）
项目根目录下的 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" } -
在含有package.json文件的项目中配置(添加"apidoc":{}参数)
{ "name": "example", "version": "0.1.0", "description": "apiDoc basic example", "apidoc": { "title": "Custom apiDoc browser title", "url" : "https://api.github.com/v1" } } -
添加额外的 Header 和 Footer (不常用，在apidoc.json添加header和footer参数)
{ "header": { "title": "My own header title", "filename": "header.md" }, "footer": { "title": "My own footer title", "filename": "footer.md" } } -
配置参数的详细说明(apidoc.json)
参数名 描述 name 项目名称，若不存在该字段，则会尝试取 package.json 里面的name值 version 项目版本号，不存在则读取 package.json 里面对于的值 description 项目描述 ，不存在同上 title 浏览器标题文本 url api路径的前缀，适合同一域下的接口，例：https://api.github.com/v1 sampleUrl 测试样例的url, 具体请参考 @apiSampleRequest header 添加自定义的顶部描述 {title: '', filename: ''} title 顶部的标题 filename 顶部具体的展现内容 footer 添加自定义的尾部描述 {title: '', filename: ''} title 尾部的标题 filename 尾部具体的展现内容 order 用于定义输出的api-names/group-name列表排序。最后自动显示未定义的名称。"order": ["Error","Define","PostTitleAndError","PostError"]
五、apiDoc 常用api说明
-
常用api：
@api,@apiName,@apiGroup,@apiVersion,@apiDescription,@apiParam,@apiSuccess,@apiSuccessExample,@apiDefine,@apiError,@apiIgnore -
基本例子(demo.js)
/** * @api {get} /user/:id Request User information * @apiVersion 0.1.0 * @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" * } */说明：文档块以
/**和*/结尾，其中@api为必须字段，格式同例子：@api + {请求类型} + 接口路径 + 接口描述，在生成的时候没有@api 的文档块会被忽略。@apiName和@apiGroup,在版本迭代时应保持一致，其他字段为可选。 -
@api (必须字段，没有会被忽略)
@api {method} path [title]例：@api {get} /user/:id Users unique ID.
-
@apiParam
@apiParam [(group)] [{type}] [field=defaultValue] [description]示例：
/** * @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. */说明：1. 带括号的Fieldname将Variable定义为可选。2. =defaultValue 参数默认值。
-
@apiSuccess
@apiSuccess [(group)] [{type}] field [description]示例：
/** * @api {get} /user/:id * @apiSuccess {String} firstname Firstname of the User. * @apiSuccess {String} lastname Lastname of the User. */ /** * @api {get} /user/:id * @apiSuccess (200) {String} firstname Firstname of the User. * @apiSuccess (200) {String} lastname Lastname of the User. */ /** * @api {get} /user/:id * @apiSuccess {Boolean} active Specify if the account is active. * @apiSuccess {Object} profile User profile information. * @apiSuccess {Number} profile.age Users age. * @apiSuccess {String} profile.image Avatar-Image. */ ```
六、示例代码下载
七、demo示例效果图
1532659983362.jpg
1532660016333.jpg
jsDoc的使用教程
一、安装
# 全局安装方式
npm install -g jsdoc
# 查看安装是否成功
jsdoc -v
# 基本使用方式
jsdoc demo.js
二、jsdoc 常用命令说明
| 指令简写 | 指令全称 | 说明 |
|---|---|---|
| -f | --file-filters | 过滤器，指定应该解析的文件类型，后缀 （可以使用多个-f）。默认.cs .dart .erl .go .java .js .php .py .rb .ts。示例（仅解析.js和.ts文件）：apidoc -f ".*\.js" -f ".*\\.ts" |
| -e | --exclude-filters | 过滤器用于选择不应该解析的文件 |
三、具体使用
- 命令行新建一个项目
mkdir jsDocDemo
cd jsDocDemo
npm init -y
- 新建一个demo.js,代码示例如下:
/**
* Book类，代表一个书本.
* @constructor
* @param {string} title - 书本的标题.
* @param {string} author - 书本的作者.
*/
function Book(title, author) {
this.title=title;
this.author=author;
}
Book.prototype={
/**
* 获取书本的标题
* @returns {string|*}
*/
getTitle:function(){
return this.title;
},
/**
* 设置书本的页数
* @param pageNum {number} 页数
*/
setPageNum:function(pageNum){
this.pageNum=pageNum;
}
};
- 命令行编译文件
jsdoc demo.js
注： 默认生成在 out 目录下，更换目录可使用 -d + 文件夹路径
标签：String,title,ApiDoc,接口,js,api,文档,apiSuccess,apidoc 来源： https://www.cnblogs.com/ExMan/p/11475705.html
本站声明： 1. iCode9 技术分享网（下文简称本站）提供的所有内容，仅供技术学习、探讨和分享； 2. 关于本站的所有留言、评论、转载及引用，纯属内容发起人的个人观点，与本站观点和立场无关； 3. 关于本站的所有言论和文字，纯属内容发起人的个人观点，与本站观点和立场无关； 4. 本站文章均是网友提供，不完全保证技术分享内容的完整性、准确性、时效性、风险性和版权归属；如您发现该文章侵犯了您的权益，可联系我们第一时间进行删除； 5. 本站为非盈利性的个人网站，所有内容不会用来进行牟利，也不会利用任何形式的广告来间接获益，纯粹是为了广大技术爱好者提供技术内容和技术思想的分享性交流网站。