api文档生成器apidoc的安装和使用
来源:互联网 发布:淘宝发展史宣传片 编辑:程序博客网 时间:2024/03/28 18:53
在开发接口的过程中,需要向外发布相应的接口文档。开始的时候使用word来写文档,时间长了发现有几个问题。
1. 编写不方便。每次新增借口的时候都要复制上一个接口,然后再进行修改,一些相同的部分无法复用,接口多了文档会变的很长,还经常需要调整格式。
2. 发布不方便。文档更新时,需要发给需要的小伙伴。即使用git来进行管理,虽然拉取比较方便,但由于文件格式的问题,也不方便比较两次提交的差异。
由于有这些问题,决定寻找一种更优雅有效的方式来编写文档。经过比较,发现了apidoc,可以比较好的解决上面提到的问题。apidoc采用了一种类似写代码注释的方式来写文档,支持编写多种语言的文档。最后生成的文档以网页的形式发布,方便快捷,便于阅读。下面就来简单介绍一下怎么使用apidoc来写文档。
安装
1. 由于apidoc依赖node.js的包管理工具npm进行安装,所以安装apidoc之前要先安装node.js(npm会在安装node时顺带进行安装)。具体的安装教程可以参考这里。
2. 安装完了npm之后,就可以安装apidoc了。在命令行输入
npm install apidoc -g
就可以进行安装了。安装完成输入
apidoc -h
出现相关的提示帮助信息,说明安装成功了。
使用
1. 在需要生成文档的地方新建一个apidoc.json文件,配置如下
{ "name": "appleFarm",//文档项目名 "title": "appleFarmAPI",//html标题 "description":"appleFarmAPI接口文档",//文档描述 "url" : "https://farm.05948166.com",//公共接口地址 "version": "0.1.0"//文档版本}
2. 在新建apidoc.json的地方打开命令行输入apidoc即可在本目录下生成doc目录直接访问即可
语法
举个栗子
/** * @api {get} /articles/:id 根据单个id获取文章信息 * @apiName 根据id获取文章信息 * @apiGroup Articles * * @apiParam (params) {String} id 文章id * * @apiSuccess {Array} article 返回相应id的文章信息 * * @apiSuccessExample Success-Response: * HTTP/1.1 200 OK * { * "tile": "文章标题2", * "date": 1483941498230, * "author": "classlfz", * "content": "文章的详细内容" * } * * @apiError (Error 4xx) 404 对应id的文章信息不存在 * * @apiErrorExample Error-Response: * HTTP/1.1 404 对应id的文章信息不存在 * { * "error": err * } */
详细介绍
@api
@api一般是必须编写的(除非你是用了@apiDefine),不然apidoc编译器会忽略这段注释。
/** * @api {method} path [title] */
@apiGroup
定于api归属的组名,生成的文档会把该api注释归类到该值对应的api组上。
/** * @apiGroup name */
@apiName
@apiName用于定义API文档的一个实例,并用作实例名称 。
/** * @apiName name */
@apiParam
@apiParam用于编写API的参数以及参数的解释。
/** * @apiParam [(group)] [{type}] [field=defaultValue] [description] */
@apiParamExample
@apiParamExample参数举例
/** * @apiParamExample [{type}] [title] * example */
@apiSuccess
请求成功后的返回字段参数
/** * @apiSuccessExample [{type}] [title] example */
@apiSuccessExample
请求成功后返回的字段参数例子
/** * @apiSuccessExample [{type}] [title] example */
@apiError & @apiErrorExample
这个的用法跟@apiSuccess、@apiSuccessExample的用法相类似。
0 0
- api文档生成器apidoc的安装和使用
- 使用apidoc生成restful-api文档:安装nodejs+npm+apidoc
- apidoc ----api文档生成工具的使用
- apidoc的安装和使用
- apidoc 安装与使用示例生成 Api文档
- 【推荐】apidoc api文档生成工具的使用(mac)
- Web API文档生成工具apidoc 的使用步骤
- apidoc使用教程-编写漂亮的api文档
- 使用apidoc 生成Restful web Api文档
- 使用apidoc 生成Restful web Api文档
- 如何使用apidoc来自动更新API文档
- 使用apidoc 生成Restful web Api文档
- apidoc 生成api文档
- apidoc的介绍和使用
- apidoc的介绍和使用
- 开发API必备神器---ApiDoc的使用
- 使用apidoc自动生成rest风格api接口文档
- ApiDoc 自动生成API文档
- django3
- Maven的安装配置以及Eclipse中Maven插件的安装和配置
- 逆向工程核心原理学习笔记(二十五):abex'crackme #2初步破解
- MTK平台连接电脑无法进入adb shell解决方法
- [人工智能]机器学习实践中数据和模型的选择
- api文档生成器apidoc的安装和使用
- 【智库2861】大数据制造失业or创造就业?
- poj2155二维线段树
- Github上十大C#开源项目排行榜
- [NOI2015] BZOJ4195 程序自动分析-离散化-并查集
- C/C++:二分法查找近似根
- 【智库2861】大数据就是占有数据?错,如何使用更重要!
- C919简介
- 创意视觉应用︱基于深度学习的CVaaS计算机视觉即服务案例(Computer Vision as a Service)