API开发接口文档开发利器：apidoc

2021-10-22 11:08:33
794次极悦

apidoc介绍：

apidoc可以根据代码注释生成web api文档，支持大部分主流语言java javascript php coffeescript erlang perl python ruby go...，相对而言，web接口的注释维护起来更加方便，不需要额外再维护一份文档。apidoc从注释生成静态html网页文档，不仅支持项目版本号，还支持api版本号。

本例基于nutz开源框架构建,写的文档，可以借鉴

如上边的修改密码的样子生成模板：

package cn.lvche.doc; 
/**
 * @author William 2017年12月12日14:57:49 
 *
 */
public class UserInfoModifyApiDoc { 
}
/**
 * @api {post} localhost:8011/user/modifyInfo/do____『2017年12月12日14:57:56』      W-用户信息修改
 * @apiGroup user
 * @apiVersion 1.0.0
 * @apiPermission anyOne  
 * @apiParam {String}	userAccount 			账号
 * @apiParam {String}	nickName 				昵称
 * @apiParam {String}	email 				              邮箱
 *
 * @apiSuccess {string} returnCode 			              返回码
 * @apiSuccess {string} code 			                            返回码
 * @apiSuccess {string} msg 			                            提示语
 * @apiSuccess {[Object]} data 			      	数据对象		    	
 * @apiSuccess {String} data.fduserid			用户id
 * @apiSuccess {String} data.fduseracc			用户账号
 * @apiSuccess {String} data.fdusercreateat		用户创建时间
 * @apiSuccess {String} data.fdusername			用户名
 * @apiSuccess {String} data.fduseremail		用户邮箱
 * @apiSuccess {String} data.fduserqq			用户qq
 * @apiSuccess {String} data.fdusermsn 			用户msn
 * @apiSuccess {String} data.fdusersort			用户排序
 * @apiSuccess {String} data.fduserstatus		登录状态
 * @apiSuccess {String} data.fduserloginip		登录ip
 * @apiSuccess {String} data.fduserloginat		用户登录时间
 * @apiSuccess {String} data.fduserkey			用户key
 * @apiSuccess {String} data.fduserdepartment	用户部门
 * @apiSuccess {String} data.fdusergrade		用户等级
 * @apiSuccess {String} data.fduserphone		用户手机号
 * @apiSuccess {String} data.userAvatar			用户头像
 * @apiSuccess {String} data.sessionKey			sessionKey
 * @apiSuccess {String} data.companyNum			企业号
 * @apiSuccess {String} data.companyInfo		 企业信息		
 * @apiSuccess {String} data.ip					企业ip
 * @apiSuccess {String} data.port				企业端口号  
 * @apiSuccessExample {json} 示例
 * 参数例子:
 * =====================================================
 * userAccount:william
 * nickName:管***
 * email:****@jo****.com
 * =====================================================
 * HTTP/1.1 200 OK
 *
{
    "returnCode": "SUCCESS",
    "code": "0",
    "msg": "登录成功！",
    "data": {
        "fduserid": "1",
        "fduseracc": "ad***",
        "fdusercreateat": "2008-11-14",
        "fdusername": "***",
        "fduseremail": "***@***len.com",
        "fduserqq": "123456789",
        "fdusermsn": "wHy@****eage.com",
        "fdusersort": "1",
        "fduserstatus": "1",
        "fduserloginip": "192.168.1.134",
        "fduserloginat": "2017-12-07",
        "fduserkey": "636396144571760904",
        "fduserdepartment": "技术部",
        "fdusergrade": "1",
        "fduserphone": "",
        "userAvatar": "http://www.qqzhi.com/uploadpic/2015-02-02/211841154.jpg",
        "sessionKey": "123456789123456789dddddd",
        "companyNum": "123456",
        "companyInfo": "潮流前线",
        "ip": "127.0.0.1",
        "port": "8080"
    }
}
 * @apiError (失败) {string} code 不等于0
 * @apiError (失败) {string} msg 错误文字描述
 * @apiErrorExample {json} 示例
 * 参数例子:
 * =====================================================
 * userAccount:
 * nickName:管***
 * email:****@jo****.com
 * =====================================================
 * HTTP/1.1 200 OK
 * 
{
    "returnCode": "ERROR",
    "code": "-1",
    "msg": "账号不能为空，请核对后再试！",
    "data": {}
}
 */

api操作更新，进入到smartC.cms根目录，dos命令窗口下执行下边语句

apidoc -i src/main/java apidoc_out

如果没有apidoc情况下，先用nodejs安装npm apidoc插件

npm install apidoc -g

附赠工作空间结构图：