再谈前后端联调

想当年，我也写过这样一篇文档，诉说一份合理的后端文档应该是怎样的。
实现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文件，浏览结果。

猜你喜欢