接口文档编写
Posted lyle-liu
tags:
篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了接口文档编写相关的知识，希望对你有一定的参考价值。
接口文档编写
1.统一返回对象：Result
|
字段 |
类型 |
说明 |
|
msg |
String |
提示消息 |
|
True/false |
Boolean |
是否报错，true请求成功，false报错 |
|
code |
Integer |
Code |
|
data |
json |
接口返回的数据（以下文档的返回字段） |
- checkitem新增
请求路径："/checkitem/add"
请求方式：post
表头：contentType: application/json;charset=UTF-8
请求参数：
|
参数 |
必选 |
类型 |
说明 |
|
code |
Y |
String |
体检代码值，长度不超过16字节 |
|
name |
Y |
String |
体检名称，长度不超过32字节 |
|
sex |
N |
Char |
性别，值为男或女 |
|
age |
N |
Integer |
年龄，数值区间0-100 |
|
type |
N |
Char |
类型，值为检查或检验 |
|
price |
N |
float |
价格，有效数字2位 |
|
attention |
N |
String |
注意事项，长度不超过128字节 |
|
remark |
N |
String |
备注，长度不超过128字节 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
返回结果：字段
|
参数 |
必选 |
类型 |
说明 |
|
flag |
Y |
boolean |
True/false，表示添加操作是否成功 |
|
Message |
Y |
String |
提示信息，例如：“添加成功” |
|
|
|
|
|
|
|
|
|
|
示例：
请求参数：
{
"code":"hw-003",
"name":"华为体重",
"sex":"男",
"age":"25",
"type":"1",
"price":"100.0",
"attention":"无",
"remark":"无"
}
返回值：
{
"data": null,
"flag": true,
"message": "新增检查项成功"
}
2. checkitem编辑
请求路径："/checkitem/edit"
请求方式：post
表头：contentType: application/json;charset=UTF-8
请求参数：
|
参数 |
必选 |
类型 |
说明 |
|
Id |
Y |
Integer |
唯一标识，最大长度为10位 |
|
code |
Y |
String |
体检代码值，长度不超过16字节 |
|
name |
Y |
String |
体检名称，长度不超过32字节 |
|
sex |
N |
Char |
性别，值为男或女 |
|
age |
N |
Integer |
年龄，数值区间0-100 |
|
type |
N |
Char |
类型，值为检查或检验 |
|
price |
N |
float |
价格，有效数字2位 |
|
attention |
N |
String |
注意事项，长度不超过128字节 |
|
remark |
N |
String |
备注，长度不超过128字节 |
返回结果：字段
|
参数 |
必选 |
类型 |
说明 |
|
flag |
Y |
boolean |
True/false，表示添加操作是否成功 |
|
Message |
Y |
String |
提示信息，例如：“添加成功” |
示例：
请求参数：
{
"id":"97",
"code":"hw-001",
"name":"华为血压",
"sex":"男",
"age":"25",
"type":"1",
"price":"100.0",
"attention":"无",
"remark":"无"
}
返回值：
{
"data": null,
"flag": true,
"message": "编辑检查项成功"
}
3. checkitem根据id查询，回显数据
请求路径："/checkitem/findById"
请求方式：get
表头：contentType: application/json;charset=UTF-8
请求参数：
|
参数 |
必选 |
类型 |
说明 |
|
Id |
Y |
Integer |
唯一标识，最大长度为10位 |
返回结果：字段
|
参数 |
必选 |
类型 |
说明 |
|
code |
Y |
String |
体检代码值，长度不超过16字节 |
|
name |
Y |
String |
体检名称，长度不超过32字节 |
|
sex |
N |
Char |
性别，值为男或女 |
|
age |
N |
Integer |
年龄，数值区间0-100 |
|
type |
N |
Char |
类型，值为检查或检验 |
|
price |
N |
float |
价格，有效数字2位 |
|
attention |
N |
String |
注意事项，长度不超过128字节 |
|
remark |
N |
String |
备注，长度不超过128字节 |
示例：
请求参数：http://localhost:83/checkitem/findById.do?id=98
返回结果：
{
"data": {
"age": "25",
"attention": "无",
"code": "hw-002",
"id": 98,
"name": "华为体重",
"price": 100,
"remark": "无",
"sex": "男",
"type": "1"
},
"flag": true,
"message": "回显检查项成功"
}
4. checkitem 分页查询：
请求路径："/checkitem/findPage"
请求方式：get
表头：contentType: application/json;charset=UTF-8
请求参数：
|
参数 |
必选 |
类型 |
说明 |
|
currentPage |
Y |
Integer |
当前页码（要查询第几页） |
|
pageSize |
Y |
Integer |
一页展示多少条数据 |
|
queryString |
N |
string |
查询条件 |
|
|
|
|
|
|
|
|
|
|
返回结果：
|
参数 |
必选 |
类型 |
说明 |
|
rows |
Y |
json |
集合类型，页面要展示的数据内容 |
|
Total |
Y |
Integer |
总共有多少条数据 |
|
|
|
|
|
示例：
请求参数：
{
"currentPage": "1",
"pageSize":"2",
"queryString":""
}
返回结果：
{
"rows": [
{
"age": "0-100",
"attention": "无",
"code": "0001",
"id": 28,
"name": "身高",
"price": 5,
"remark": "身高",
"sex": "0",
"type": "1"
},
{
"age": "0-100",
"attention": "无",
"code": "0002",
"id": 29,
"name": "体重",
"price": 5,
"remark": "体重",
"sex": "0",
"type": "1"
}
],
"total": 69
}
5. checkitem 根据id删除：
请求路径："/checkitem/delete"
请求方式：get
表头：contentType: application/json;charset=UTF-8
请求参数：
|
参数 |
必选 |
类型 |
说明 |
|
Id |
Y |
Integer |
唯一标识，最大长度为10位 |
返回结果：
|
参数 |
必选 |
类型 |
说明 |
|
flag |
Y |
boolean |
True/false，表示添加操作是否成功 |
|
Message |
Y |
String |
提示信息，例如：“添加成功” |
|
|
|
|
|
示例：
请求：http://localhost:83/checkitem/delete.do?id=98
返回结果：
{
"data": null,
"flag": true,
"message": "删除检查项成功"
}
以上是关于接口文档编写的主要内容，如果未能解决你的问题，请参考以下文章