想当年,我也写过这样一篇文档,诉说一份合理的后端文档应该是怎样的。
实现API接口文档编写工作,有很多种方式,Word文档,MediaWiki,利用Swagger自动化生成文档,自己写confluence文档,利用Web API文档生成工具apidoc。
下面将着重介绍confluence文档和apidoc文档。
一、confluence文档
下面以档案查询为例,说明在接口联调过程中,后端提供什么给前端。
1、request地址
http://www.xxx.com/archive/api/obj/abstract/search
2、request参数
a、参数字段
字段 | 类型 | 描述 |
moduleCode
|
String
|
模型编码
|
paramList
|
Array
|
查询对象list
|
objType
|
String
|
对象类型
|
objValue
|
String
|
对象标识
|
b、参数模版
{ "moduleCode": "abstract4detail", "paramList": [ { "objType": "101001", "objValue": "12345678912345670" }, { "objType": "101001", "objValue": "12345678912345671" } ] }
2、response参数
a、参数字段
字段 | 类型 | 描述 |
success
|
Boolean
|
true/false 表示请求接口是否成功。true表示成功,false失败
|
code
|
Number
|
对应状态编码
|
message
|
String
|
返回说明,比如接口响应失败。
|
data
|
Array
|
具体的数据信息。
|
b、参数模版
{ "success": true, "code": 0, "message": null, "data": [ { "objType": "101001", "name": "张三", "objValue": "123456789012345670", "country": "中国", "photo": "151563352152651025641222225545265561156" } ] }
二、apidoc文档
通过源码中的注释来生成 Web API 文档。
1、安装node,并安装apidoc包
sudo npm install apidoc -g
2、在mydoc工程中,新建apidoc.json文件
{ "name": "example", "version": "0.1.0", "description": "A basic apiDoc example" }
3、在mydoc工程中,新建test.java文件
/** * @api {get} /user/:id Request User information * @apiName GetUser * @apiGroup User * * @apiParam {Number} id Users unique ID. * * @apiSuccess {String} firstname Firstname of the User. * @apiSuccess {String} lastname Lastname of the User. * * @apiSuccessExample Success-Response: * HTTP/1.1 200 OK * { * "firstname": "John", * "lastname": "Doe" * } * * @apiError UserNotFound The id of the User was not found. * * @apiErrorExample Error-Response: * HTTP/1.1 404 Not Found * { * "error": "UserNotFound" * } */
4、执行命令,生成文档
apidoc -i mydoc/ -o mydoc/doc/
5、打开index.html文件,浏览结果。