APIDoc自动生成接口文档

凡梦星尘

发布于 2024-11-20 17:22:42

7800

对于项目开发常见的前后端分离模式来说，中间在后端完成接口开发交付对接时，前端人员往往苦于没有接口文档会经常"跑去"骚扰后端人员，真是苦不堪言哪。要是此时有个文档化的说明那就轻松多啦，现在后端流行的文档生成利器有Swagger，它虽然方便，但是也有弊端得写在的后台的代码中，而且启动整个后台项目才能访问。或许有时还真不太方便的，另外就是项目初期要对接口做个规划也无法用这个方法，难道就没有别的办法了嘛？

最后在浩瀚的网络中还是找到个不错的工具—— Nodejs APIDoc ，非常的强大，支持当前流行的开发语言，如Java,PHP,JavaScript,Python,Ruby等等，下面就来简单的介绍下它的使用方法。

安装模块

前面的介绍中已经说了它是基于NodeJS环境，所以你必须先有个NodeJS环境，然后就是安装下APIDoc模块，参考命令如下：

1	npm install apidoc -g

工程配置文件

接下来创建个工程文件夹，并入个工程的配置文件，参考如下：

1 2 3 4 5 6 7 8 9 10 11 12	{ "name": "XXXX开放接口平台", "version": "1.0.1", "description": "XXXX开放接口平台，设计所有与第三方服务对接的接口服务。请注意所有的接口数据交互格式为JSON格式。", "title": "XXXX开放接口平台", "generator": { "name": "XXXX", "time": "2017-07-18 15:46:55", "url": "https://xxxx.com", "version": "1.0.1" } }

接口文档

所有相关的准备工作完成后，那么此时我们就需要来写关于接口描述的文档，这个具体要看你今后实际项目的开发语言，建议尽量选择相同的，在此我就以Java为示例，不需要具体的代码，只需填充代码注释部分的内容，参考如下：

hello-api.java

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98

/** * @apiDefine xxxxx * * XXX 当前接口文档名称(一般就对接客户的名称) */ /** * @apiDefine Err400 * * @apiError {String} tranDate 发生交易的日期 * @apiError {String} tranTime 发生交易的时间 * @apiError {String} serviceId 机构代码(东吴提供) * @apiError {Number} resultCode 1,表示成功,0表示失败 * @apiError {String} resultComment 失败原因描述 * * @apiErrorExample Error400-Response: * HTTP/1.1 400 * { * "tranDate": "20170718", * "tranTime": "131223", * "serviceId": "xxxx", * "resultCode": 0, * "resultComment": "请求数据语法格式有误." * } */ /** * @apiDefine Suc200 * * @apiSuccess {String} tranDate 发生交易的日期 * @apiSuccess {String} tranTime 发生交易的时间 * @apiSuccess {String} serviceId 机构代码(东吴提供) * @apiSuccess {Number} resultCode 1,表示成功,0表示失败 * @apiSuccess {String} resultComment 失败原因描述 * * @apiSuccessExample Success-Response: * HTTP/1.1 200 * { * "tranDate": "20170718", * "tranTime": "131223", * "serviceId": "xxxx", * "resultCode": 1, * "resultComment": "Success" * } */ /** * @apiDefine AccessKey * * @apiHeader {String} access-key 加密密钥: 当前日期+指定字符串的32位MD5加密字符串. * * @apiHeaderExample {json} Header-Example: * { * "access-key": "cfa1fd55a89f45c9800120d6cbff0b33" * } */ /** * @api {PUT} /dwhealath/synccustomerinfo.do 同步客户基础信息 * @apiDescription 批量次同步客户的基础信息，建议每个批次不要大于1000条记录。 * * @apiVersion 1.0.1 * @apiName customer * @apiGroup dwHealth * * @apiUse AccessKey * * @apiParam {String} cusName 姓名 * @apiParam {String} cusSex 性别 * @apiParam {String} cusBirthday 生日 * @apiParam {String} cusIdType 证件类型 * @apiParam {String} cusIdNo 证件号码 * @apiParam {String} cusCompanyId 工作单位 * @apiParam {String} cusServItemNo 计划编号 * * @apiParamExample {json} Request-Example: * { * "serviceId": "xxxx", * "data": [ * { * "cusName": "张三", * "cusSex": "男", * "cusBirthday": "2017-07-18", * "cusIdType": "身份证", * "cusIdNo": "4419381788902217652", * "cusCompanyId": "1024", * "cusServItemNo": "201707181313132", * } * ...... * ] * } * * @apiUse Suc200 * * @apiUse Err400 * */