【其他】接口设计文档模板

前言

后端接口设计文档，个人认为需要告知接口调用者的内容
博客地址：芒果橙的个人博客 【http://mangocheng.com】

---

接口设计说明-xx系统

修改记录

本次修改记录，每次更新后删除，只显示当次内容

日期：2020-05-01~2020-05-06

1. 新增权限模块第3章节内容

接口清单

序号	模块	说明
1	权限模块	主要包含用户的权限功能接口

一、权限模块

序号	接口	说明
1	searchAuthority	获取当前登录用的权限

预定义

• 参数类型未标明，默认皆为字符串

1. 获取用户权限

1）功能说明

获取当前登录用的权限，菜单加功能

2）接口说明

• 请求方式：GET
• 请求地址：http://ip:port/authority/searchAuthority
• 请求参数： 无

3）请求参数

• 示例

http://10.254.11.82:7013/authority/searchAuthority

• 1

4）响应参数

参数名	类型	说明
data	Map	权限对象
status	String	状态：1-成功，0-失败
httpCode	String	Http返回码
errCode	String	错误码
errMessage	String	错误信息

• 示例

{
  "status": 1,
  "data": {
    "MENU": [
      "CLUE",
    ]
  },
  "httpCode": 200,
  "errCode": 0,
  "errMessage": ""
}

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11

2.保存或更新菜单

1）功能说明

菜单管理，新增或更新菜单

2）接口说明

• 请求方式：POST
• 请求地址：http://ip:port/authority/saveOrUpdateMenu
• 请求参数：menuVO

3）请求参数

• MenuVO：菜单对象

参数名	类型	说明
type	String	操作类型（CREATE–新增；UPDATE–更新）
menuPO	TMenuPO	菜单实体类

• 示例1：菜单新增

{
  "menuPO": {
      "id": "",
      "name": "菜单名称1"
  },
  "type": "CREATE"
}

• 1
• 2
• 3
• 4
• 5
• 6
• 7

• 示例2：菜单更新

{
  "menuPO": {
      "id": "23LebronJames",
      "name": "菜单名称23"
  },
  "type": "UPDATE"
}

• 1
• 2
• 3
• 4
• 5
• 6
• 7

4）响应参数

参数名	类型	说明
data	List<String>	保存/更新结果主键集合（ryid）
status	String	状态：1-成功，0-失败
httpCode	String	Http返回码
errCode	String	错误码
errMessage	String	错误信息

• 示例1：菜单新增

{
  "status": 1,
  "data": [
    "24Kobe"
  ],
  "httpCode": 0,
  "errCode": 0,
  "errMessage": ""
}

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9

• 示例2：菜单更新

{
  "status": 1,
  "data": [
    "23James"
  ],
  "httpCode": 200,
  "errCode": 0,
  "errMessage": ""
}

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9

---

二、xx模块

该模块的所有接口及其简要说明

序号	接口	说明
1	xx	xx

预定义

• 预先定义一些默认的、公共的说明

1. xx接口

1）功能说明

该接口的功能是什么

2）接口说明

• 请求方式：GET/POST
• 请求地址：接口地址
• 请求参数： 方法参数名称

3）请求参数

接口的请求参数说明

• 示例

请求参数示例

• 1

4）响应参数

接口的响应参数说明

参数名	类型	说明
xx	xx	xx

• 示例

响应参数的示例