利用apidoc维护api接口文档

shaonbean 发布于2019-07-30 14:42 / 3586人阅读

摘要：什么是是一个轻量级的在线接口文档生成系统，支持多种主流语言，包括和等。使用者按照要求书写相关注释，就可以生成可读性好界面美观的在线接口文档。双击文件夹下的，就能看到文档了。

什么是apidoc

apidoc是一个轻量级的在线REST接口文档生成系统，支持多种主流语言，包括Java、C、C#、PHP和Javascript等。使用者按照要求书写相关注释，就可以生成可读性好、界面美观的在线接口文档。

这里了解更多

快速开始

安装依赖

安装nodejs https://nodejs.org/官网下载.msi文件；
测试是否安装成功 npm -v

npm的安装。由于新版的NodeJS已经集成了npm，所以之前npm也一并安装好了。同样可以使用cmd命令行输入"npm -v"来测试是否成功安装。如下图，出现版本提示便OK了。

安装apidoc

利用npm进行安装

npm install apidoc -g

安装速度和网速有关，最多1到2分钟，

apidoc -v  可以查看版本信息

安装好后在

C:UsersadminAppDataRoaming
pm
ode_modulesapidoc

能够看到如下文件

apidoc配置

打开example文件夹apidoc.json为配置文件,修改参数为自己的项目信息。

{
  "name": "apidoc-example",
  "version": "0.3.0",
  "description": "apidoc example project",
  "title": "Custom apiDoc browser title",
  "url" : "https://api.github.com/v1",
  "sampleUrl": "https://api.github.com/v1",
  "header": {
    "title": "My own header title",
    "filename": "header.md"
  },
  "footer": {
    "title": "My own footer title",
    "filename": "footer.md"
  },
  "template": {
      "withCompare": true,
      "withGenerator": true
  }
}

将 apidoc.json 拷贝到需要生成文档的目录下

然后按照文档说明做代码注释

/**
 * @api {get} /sguoshan_api/Logon 获取用户信息
 * @apiVersion 1.0.0
 * @apiName  Logon
 * @apiGroup User
 * @apiPermission 所有已注册用户
 * @apiPrivate
 * @apiDescription 与0.9.0相比安全性提高
 *
 * @apiParam {String} username 用户名称/邮箱/会员号
 * @apiParam {Number} password 用户密码
 * @apiExample 使用示例:
 * http://api.guoshanchina.com/sguoshan_api/Logon?username=911117&password=123456
 *
 * @apiSuccess {Number}   id            The Users-ID.
 * @apiSuccess {Date}     registered    Registration Date.
 * @apiSuccess {Date}     name          Fullname of the User.
 * @apiSuccess {String[]} nicknames     List of Users nicknames (Array of Strings).
 * @apiSuccess {Object}   profile       Profile data (example for an Object)
 * @apiSuccess {Number}   profile.age   Users age.
 * @apiSuccess {String}   profile.image Avatar-Image.
 * @apiSuccess {Object[]} options       List of Users options (Array of Objects).
 * @apiSuccess {String}   options.name  Option Name.
 * @apiSuccess {String}   options.value Option Value.
 *
 * @apiSuccessExample 成功 return ():
{
"msg": "获取成功",
"status":"200",
"data":{
    "id":"123",
    "name":"shmily"
    }
}
 * @apiError NoAccessRight     只用登陆成功才能访问.
 * @apiError UserNotFound   用户 id 错误.
 * @apiErrorExample 失败 return ():
 *     HTTP/1.1 401 Not Authenticated
 *     {
 *       "msg": "没有权限","status":"401"
 *     }
 */
function getUser() { return; }

在命令行中

切换到项目apidoc.json的上一级（api目录）
d:
cd www/shop/Web
apidoc -i api/ -o apidoc/

运行后在api的同级目录能够看到生成了apidoc的文件夹。双击文件夹下的index.html，就能看到文档了。

GPU云服务器云服务器 api接口文档 api短信接口文档快递api接口文档 api接口文档工具

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/40870.html

利用apidoc维护api接口文档

摘要：什么是是一个轻量级的在线接口文档生成系统，支持多种主流语言，包括和等。使用者按照要求书写相关注释，就可以生成可读性好界面美观的在线接口文档。双击文件夹下的，就能看到文档了。什么是apidoc apidoc是一个轻量级的在线REST接口文档生成系统，支持多种主流语言，包括Java、C、C#、PHP和Javascript等。使用者按照要求书写相关注释，就可以生成可读性好、界面美观的在线接...

hiyayiji 2019-06-28 13:50 评论0 收藏0
利用apidoc维护api接口文档

摘要：什么是是一个轻量级的在线接口文档生成系统，支持多种主流语言，包括和等。使用者按照要求书写相关注释，就可以生成可读性好界面美观的在线接口文档。双击文件夹下的，就能看到文档了。什么是apidoc apidoc是一个轻量级的在线REST接口文档生成系统，支持多种主流语言，包括Java、C、C#、PHP和Javascript等。使用者按照要求书写相关注释，就可以生成可读性好、界面美观的在线接...

biaoxiaoduan 2019-08-21 16:41 评论0 收藏0
Web API 文档生成工具 apidoc

摘要：实现接口文档编写工作，有很多种方式，例如通过文档编写，或者通过进行维护。这里，笔者想分享另一个文档生成工具。此外，可以支持多种语言，，，，，，。查询签收预警策略查询签收预警策略平台类型商家名称最后，我们在终端输入命令进行文档生成。原文地址：梁桂钊的博客在服务端开发过程中，我们需要提供一份 API 接口文档给 Web 端和移动端使用。实现 API 接口文档编写工作，有很多种方式，例...

sushi 2019-08-15 13:47 评论0 收藏0
[原] Python 开发者面向文档编程的正确姿势

摘要：用注释写单元测试单元测试是代码开发环节必不可少的一环，对于定位和代码质量而言是非常重要的。现在最广为人知的单元测试框架就是，它借鉴了中成熟的单元测试框架的。概述 showImg(https://segmentfault.com/img/bVD66s?w=550&h=550); 秦人不暇自哀,而后人哀之;后人哀之而不鉴之,亦使后人而复哀后人也! --论面向文档编程的重要性如果想看见识...

Y3G 2019-07-25 10:51 评论0 收藏0