工作笔记7 - java中apidoc文档生成工具等简单应用

阅读更多

Apidoc使用手册

简介

在项目开发过程中，可能会用到文档生成工具 
该工具是Nodejs的模块，请务必在使用前安装好nodejs环境！

工具名称：apiDoc 
Git地址：https://github.com/apidoc/apidoc 
项目地址：http://apidocjs.com/ 
样例项目：http://apidocjs.com/example_basic/ 

支持的注释样式: 
JavaDoc-Style

/**

 * This is a comment.

 */

安装apidoc

命令行输入 

npm installapidoc –g

 

输入apidoc –v

命令查看是否安装成功

使用方式

在命令行输入

apidoc -f ".*\\.js$" -f ".*\\.java$" -i myapp/ -o apidoc/ -t mytemplate/

 

参数说明： 
-f 文件过滤 
使用正则表达式，表示哪些文件需要本转换，不设置的情况下，默认为.cs .dart .erl .go .java .js .php .py .rb .ts 后缀的文件。

-i 代码文件夹

-o 输出Api文档的路径

-t 使用模板文件的路径，可以自定义输出的模板

       

我直接用的默认配置就行了         

       生成apidoc

       打开到你的项目路径下，命令行输入

       apidoc -o apidoc/

   生成文件里的index.html用浏览器打开就是文档啦

 

 

注释的定义自己到网上去找

   附上一些例子

 

   user.java

/**
 * @api {POST} /register 注册用户
 * @apiGroup Users
 * @apiVersion 0.0.1
 * @apiDescription 用于注册用户
 * @apiParam {String} account 用户账户名 
 * @apiParam {String} password 密码
 * @apiParam {String} mobile 手机号
 * @apiParam {int} vip = 0  是否注册Vip身份 0 普通用户 1 Vip用户
 * @apiParam {String} [recommend] 邀请码
 * @apiParamExample {json} 请求样例：
*                ?account=sodlinken&password=11223344&mobile=13739554137&vip=0&recommend=
 * @apiSuccess (200) {String} msg 信息
 * @apiSuccess (200) {int} code 0 代表无错误 1代表有错误
 * @apiSuccessExample {json} 返回样例:
 *                {"code":"0","msg":"注册成功"}
 */







 /**
 * @api {POST} /login 用户登录
 * @apiGroup Users
 * @apiVersion 0.0.1
 * @apiDescription 用于用户登录
 * @apiParam {String} userName 用户名
 * @apiParam {String} password 密码
 * @apiParamExample {json} 请求样例：
 *                ?userName=张三&password=11223344
 * @apiSuccess (200) {String} msg 信息
 * @apiSuccess (200) {String} code 0 代表无错误 1代表有错误
 * @apiSuccess (200) {String} user 用户信息
 * @apiSuccess (200) {String} userId 用户id
 * @apiSuccessExample {json} 返回样例:
 *                {"code":"0","msg":"登录成功","userId":"fe6386d550bd434b8cd994b58c3f8075"}
 */






 /**
 * @api {GET} /users/:id 获取用户信息
 * @apiGroup Users
 * @apiVersion 0.0.1
 * @apiDescription 获取用户信息
 * @apiSuccess (200) {String} msg 信息
 * @apiSuccess (200) {int} code 0 代表无错误 1代表有错误
 * @apiSuccess (200) {String} name 真实姓名
 * @apiSuccess (200) {String} mobile 手机号
 * @apiSuccess (200) {String} birthday 生日
 * @apiSuccess (200) {String} email 邮箱
 * @apiSuccess (200) {String} summary 简介
 * @apiSuccess (200) {String} recommendCode 我的推荐码
 * @apiSuccess (200) {String} idCardNo 身份证号
 * @apiSuccess (200) {String} memberState 会员状态 0普通用户 1VIP 2账户冻结
 * @apiSuccess (200) {String} address 家庭住址 
 * @apiSuccess (200) {String} money 账户现金
 * @apiSuccessExample {json} 返回样例:
 * {
 *   "code": 0,
 *   "msg": "",
 *   "name": "真实姓名",
 *   "mobile": 15808544477,
 *   "birthday": "1990-03-05",
 *   "email": "[email protected]",
 *   "summary": "简介",
 *   "recommendCode": "我的推荐码",
 *   "idCardNo": "身份证号",
 *   "memberState": 1,
 *   "address": "家庭住址",
 *   "money": "30.65"
 * }
 */







 /**
 * @api {POST} /users/:id 修改(完善)用户信息
 * @apiGroup Users
 * @apiVersion 0.0.1
 * @apiDescription 修改(完善)用户信息
 * @apiParam (200) {String} [name] 真实姓名
 * @apiParam (200) {String} [mobile] 手机号
 * @apiParam (200) {String} [birthday] 生日
 * @apiParam (200) {String} [email] 邮箱
 * @apiParam (200) {String} [summary] 简介
 * @apiParam (200) {String} [idCardNo] 身份证号
 * @apiParam (200) {String} [address] 家庭住址
 * @apiSuccess (200) {String} msg 信息
 * @apiSuccess (200) {int} code 0 代表无错误 1代表有错误
 * @apiSuccessExample {json} 返回样例:
 *                {"code":"0","msg":"修改成功"}
 */