发表于： 2017-12-08 22:46:06
1 873
今日完成的事情：
今天和前端的伙伴商讨了一下接口文档的事情，其实都是第一次做，也不知道该做些什么。
然后我就和我的后端小伙伴划分了一下，他负责写前台的接口文档，我负责写后台的接口文档。
然后学习了一波标准的接口文档应该如何写：
首先是约定，预定大于配置：
约定一些状态码，并且状态码对应的信息。
/u是必须登陆才能访问的接口。
/a不太了解，看到大家都写上了。
所有的返回字段都包含code和Message。
然后找了一个rap的写接口的工具，然后悲剧就发生了，等到我写了一部分的时候，回头导出数据竟然出问题，刚开始试写的时候可以正常导出，结果自己真正写了一部分的时候竟然出问题了。
然后就用word文档写，发现word文档换页的时候显示的十分不友好。
最后用excel来写，真是瞎折腾了好长时间：
写出来了一些接口，不太规范，对照着原型图来写的接口文档：
| 公司列表 | ||||
| 请求地址 | get | /a/u/company/list | ||
| 请求参数 | ||||
| 返回参数 | ||||
| 字段 | 说明 | 类型 | 备注 | |
| code | 状态码 | number | ||
| message | 状态说明 | string | ||
| company | 公司信息 | object | ||
| company | ||||
| 字段 | 说明 | 类型 | 是否必填 | 备注 |
| id | 序号 | number | 是 | |
| name | 公司名称 | string | 是 | |
| industry | 公司行业 | number | 是 | |
| province | 省 | string | 是 | |
| city | 市 | string | 是 | |
| financing | 融资规模 | number | 是 | |
| identify | 认证状态 | number | 是 | |
| freeze | 冻结状态 | number | 是 | |
| 新建公司 | ||||
| 请求地址+A49:D67 | post | /a/u/company | ||
| 请求参数 | ||||
| 字段 | 说明 | 类型 | 是否必填 | 备注 |
| id | 公司id | number | 是 | |
| name | 公司名称 | string | 是 | |
| slogan | 公司slogan | string | 是 | |
| totalNum | 公司人数 | number | 是 | |
| financing | 融资规模 | number | 是 | |
| province | 省 | string | 是 | |
| city | 市 | string | 是 | |
| industry | 公司行业 | number | 是 | |
| logo | 公司logo | string | 是 | |
| introduce | 公司介绍 | string | 是 | |
| tag | 公司标签 | objiect | 是 | |
| tag | ||||
| 字段 | 说明 | 类型 | 是否必填 | 备注 |
| tag | 公司标签 | string | 否 | |
| product | ||||
| 字段 | 说明 | 类型 | 是否必填 | 备注 |
| name | 产品名称 | string | 否 | |
| slogan | 产品slogan | string | 否 | |
| logo | 产品logo | string | 否 | |
| introduce | 产品简介 | string | 否 | |
| 招聘公司相关信息 | ||||
| 字段 | 说明 | 类型 | 是否必填 | 备注 |
| phone | 手机 | string | 是 | |
| 邮箱 | string | 是 | ||
| address | 详细地址 | string | 是 | |
| map | 地图 | string | 是 | |
| 返回参数 | ||||
| 字段 | 说明 | 类型 | 备注 | |
| code | 状态码 | number | ||
| message | 状态说明 | string | ||
| 修改公司 | ||||
| 请求地址 | put | /a/u/company/{companyId} | ||
| 请求参数 | ||||
| 字段 | 说明 | 类型 | 是否必填 | 备注 |
| id | 公司id | number | 是 | |
| name | 公司名称 | string | 是 | |
| slogan | 公司slogan | string | 是 | |
| totalNum | 公司人数 | number | 是 | |
| financing | 融资规模 | number | 是 | |
| province | 省 | string | 是 | |
| city | 市 | string | 是 | |
| industry | 公司行业 | number | 是 | |
| logo | 公司logo | string | 是 | |
| introduce | 公司介绍 | string | 是 | |
| tag | 公司标签 | objiect | 是 | |
| tag | ||||
| 字段 | 说明 | 类型 | 是否必填 | 备注 |
| tag | 公司标签 | string | 否 | |
| product | ||||
| 字段 | 说明 | 类型 | 是否必填 | 备注 |
| name | 产品名称 | string | 否 | |
| slogan | 产品slogan | string | 否 | |
| logo | 产品logo | string | 否 | |
| introduce | 产品简介 | string | 否 | |
| 招聘公司相关信息 | ||||
| 字段 | 说明 | 类型 | 是否必填 | 备注 |
| phone | 手机 | string | 是 | |
| 邮箱 | string | 是 | ||
| address | 详细地址 | string | 是 | |
| map | 地图 | string | 是 | |
| 返回参数 | ||||
| 字段 | 说明 | 类型 | 备注 | |
| code | 状态码 | number | ||
| message | 状态说明 | string | ||
| 删除公司 | ||||
| 请求地址 | delete | /a/u/company/{companyId} | ||
| 请求参数 | ||||
| 字段 | 说明 | 类型 | 是否必填 | 备注 |
| id | 公司id | number | 是 | |
| 返回参数 | ||||
| 字段 | 说明 | 类型 | 备注 | |
| code | 状态码 | number | ||
| message | 状态说明 | string | ||
| 修改公司状态 | ||||
| 请求地址 | put | /a/u/company/states/{companyId} | ||
| 请求参数 | ||||
| 字段 | 说明 | 类型 | 是否必填 | 备注 |
| id | 公司id | number | 是 | |
| identify | 认证状态 | number | 是 | |
| freeze | 冻结状态 | number | 是 | |
| 返回参数 | ||||
| 字段 | 说明 | 类型 | 备注 | |
| code | 状态码 | number | ||
| message | 状态说明 | string | ||
全部贴出来太长了，只贴出来了公司页面的相关接口。
原型图：
全部截图也太长了，只截取一部分。
我的接口文档是用excel写的，比较丑陋。
师兄帮忙看一下，我的接口文档有没有硬伤，或者是完全不符合规范的地方。
明日计划的事情：
继续写接口文档。
遇到的问题：
后台有一个对模块进行增加，删除和修改的接口没有思路，以前自己写的接口都是对数据进行操作，现在是对模块，就是密码修改模块，广告位模块，就是整段的代码进行操作，不知道如何下手。
收获：
学习了如何写接口文档。
返回列表
评论