nodejs 自动化生成api学习日志

   本文针对现有的技术框架nodejs+express 4.x +apidoc+leancloud部署，总结出了一套自动化生成api的方案。

一、经过塞选，选择了适合nodejs的api生成方式apidoc，这个是基于YUI的。
参考文章包括：
     apidoc示例地址：http://www.jianshu.com/p/bb5a4f5e588a
     apidoc软件地址：http://apidocjs.com/
     grunt教程：http://blog.csdn.net/wangfupeng1988/article/details/46418203
1.apidoc 的安装
方式（1）：直接安装

npm
install apidoc -g

进行安装，目前

0.12.x/4.0

都可以使用。本文直接采用的这个方案
方式（2）：采用grunt
前端自动化工具，这个进行尝试过，不过无法删除grunt-apidoc默认生成的api和进行源的筛选，需要的可以自己试一下。

2.apidoc的使用

  (1) 配置，可以新建apidoc.json,如果没有这个文件，会默认寻找package.json,下文的配置如图，生成的效果就会如图所示



 （2）文档编写，可以参考上文的地址

@api {method} path [title]

  只有使用@api标注的注释块才会在解析之后生成文档，title会被解析为导航菜单(@apiGroup)下的小菜单

  method可以有空格，如{POST GET}

@apiGroup name

  分组名称，被解析为导航栏菜单

@apiName name

  接口名称，在同一个@apiGroup下，名称相同的@api通过@apiVersion区分，否者后面@api会覆盖前面定义的@api

@apiDescription text

  接口描述，支持html语法

@apiVersion verison

  接口版本，major.minor.patch的形式

@apiIgnore [hint]

  apidoc会忽略使用@apiIgnore标注的接口，hint为描述

@apiSampleRequest url

  接口测试地址以供测试，发送请求时，@api method必须为POST/GET等其中一种

@apiDefine name [title] [description]

  定义一个注释块(不包含@api)，配合@apiUse使用可以引入注释块

  在@apiDefine内部不可以使用@apiUse

@apiUse name

  引入一个@apiDefine的注释块

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

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

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

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

  用法基本类似，分别描述请求参数、头部，响应错误和成功

  group表示参数的分组，type表示类型(不能有空格)，入参可以定义默认值(不能有空格)

@apiParamExample [{type}] [title] example

@apiHeaderExample [{type}] [title] example

@apiErrorExample [{type}] [title] example

@apiSuccessExample [{type}] [title] example

  用法完全一致，但是type表示的是example的语言类型

  example书写成什么样就会解析成什么样，所以最好是书写的时候注意格式化，(许多编辑器都有列模式，可以使用列模式快速对代码添加*号)

@apiPermission name

  name必须独一无二，描述@api的访问权限，如admin/anyone

写作示范
 


生成显示：



很多用法，待你自己开发。 
（3）生成文档
  首先设置源和目标：实例为设置源为cloud/letv
下的js文件，输出路径在根目录下的apiDoc（若没有将会自动创）



成功后 ，调用   apidoc make docs 进行文档的生成和更新。

（3）文档的部署
  apidoc生成了一个静态网页，我们现在要进行api的路由设置，使得协同开发者可以在线看。
在app.js里添加路由，方式如下



这里设置后运行发现html的静态文件找不到，因为我们设置的静态文件的路径不在这里，所以添加设置



这样静态文件就可以找到了，部署后就可以在线观看。