前后端日常吵架——接口文档谁来定义呢
和朋友聊天，他说他们公司开始了一个新项目，由他负责后端开发。因为之前做过全栈的项目，前后端开发思路都懂，就自己把逻辑走了一遍，写了api接口。结果项目开发到一半，新招了个ios，上来就说他写的接口不行吵了起来。
那么接口文档到底是该谁来定义呢？
接口是什么？API，全称是ApplicationProgrammingInterface，即应用程序编程接口，我们日常中习惯简称为“接口”。接口是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件的以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。
接口有什么用？在平时的开发过程中，前后端经常会进行数据交互，那么在前后端分离的项目中，前端就不用管后台的工作，用api调取数据即可。
接口文档该由谁来写呢？笔者认为一般接口文档一定是后端来写，只是我们要事先要和前端商量定义，然后再编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护。通俗一点就是：客户端出接口需求，服务端出接口方案。
为什么要写接口文档？1、项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发；2、项目维护中或者项目人员更迭，方便后期人员查看、维护；
接口规范是什么？首先接口分为四部分：方法、url、请求参数、返回参数1、方法:新增(post)修改(put)删除(delete)获取(get)；2、url：uri地址里不允许出现大写字母，如果是两个单词拼接，用/分开；3、请求参数和返回参数，都分为5列：字段、说明、类型、备注、是否必填；4、返回参数结构可以有一个结构体也可以有多个结构体；
如何自动生成文档？最简单的是找一个合适的工具，省去敲字对格式的痛苦。这里推荐的是Eolinker，一个适合不同规模开发团队的在线API文档工具。而且除了文档部分的功能外，整个API开发流程的不同阶段，都可以直接在Eolinker上进行，省事。
当然还有其他类似的平台也可以满足在线编辑规范接口的平台：apidoc，sosoapi等使用地址：www.eolinker.com
第一次写 API 接口文档，可以这么做
我在开始一个新的接口之前，需要进行以下判断：
请求协议是不是HTTP、https?
请求体和响应格式是什么（XML、JSON、FormData、Raw）?
API是不是RESTful风格？
如果上面三个问题的答案都清楚了，就可以开始新增一个API接口。
API信息在编辑API的顶部填写API的请求协议、方式、地址、名称；
协议支持HTTP/HTTPS请求方式支持POST
GET
PUT
DELETE
HEAD
OPTIONS
PATCH
API请求参数设置请求头部你可以输入或导入请求头部。
除了手动输入，你还可以批量导入请求头部，数据格式为key:value，一行一条header信息，如：
Connection:keep-aliveContent-Encoding:gzipContent-Type:application/json
Date:Mon,30Dec201920:49:45GMT
设置请求体请求体提供了五种类型：
Form-data（表单）
Json
XML
Raw(自定义文本类型数据)
设置Query参数Query参数指的是地址栏中跟在问号？后面的参数，如以下地址中的user_name参数：
/user/login?user_name=jackliu
批量导入的数据格式为？key=value...,通过&分隔多个参数，如：api.eolinker.com/user/login?user_name=jackliu&user_password=hello
设置REST参数REST参数指的是地址栏被斜杠/分隔的参数，如以下地址中的使用大括号包裹起来的user_name、user_password参数：
/user/login/{user_name}/{user_password}
WARNING注意，你只需要在URL中使用{}将REST参数括起来，表单的参数名不需要填写{}。
API响应内容设置响应头部你可以输入或导入响应头部。批量导入的数据格式为key:value，一行一条header信息，如：
Connection:keep-aliveContent-Encoding:gzipContent-Type:application/jsonDate:Mon,30Dec201920:49:45GMT复制代码设置响应内容响应内容的编写方式和请求参数的类似，响应内容提供了四种类型：
Json
XML
Raw(自定义文本类型数据)
以上这个工具叫Postcat，是国产的开源API工具，除了最常用的文档和测试功能，
目前的v0.2.0版本，新增团队协作功能。除此之外他们还支持：
强大的文档功能
丰富的插件市场，可拓展
前后置脚本
支持查看所有测试历史
支持Websocket协议，后续也会新增支持更多的主流协议
如果你觉得这个开源项目还可以的话，不妨点个star支持下他们，如果你觉得还需要继续优化，不妨去提个Issue.
Github：github.com/Postcatlab/…
Gitee：gitee.com/eolink\_adm…
在线Demo：
postcat.com/zh/?utm\_so…
后台接口文档示例
什么是接口文档？在项目期间，前后端是分离开发的，为了前后有连贯性，就必须由前后开发工程师共同定义接口、写接口文档再根据接口文档去开发，一直到项目结束。
接口文档规范方法也就是我们常写的新增，删除，修改，查询
url调用方法，一般是从前端调后端的方法地址
请求参数一般分五列：字段、说明、类型、备注、是否必填
返回参数1、如果只返回接口调用成功还是失败（新增、删除、修改等），则只有一个结构体：
code和message两个参数；
2、如果要返回某些参数，则有两个结构体：
是code/mesage/data；
是data里写返回的参数,data是object类型；
3、如果要返回列表，那么有三个结构体，
是code/mesage/data,data是object，里面放置page/size/total/totalPage/list5个参数，其中list是Arrary类型，list里放object，object里是具体的参数。
了解目的用户登录用户注册树形菜单文章查询文章新增文章修改文章删除用户登录：接口调用and请求
http请求方式:POST（一般有两种get/post）https://xxx.xxx.xxx:8080/项目命名/vue/userAction_login.action字段说明类型是否必填uname名字String是pwd密码String是登录成功返回JSON数据包:{"msg":"登录成功","result":{"uname":"用户名","pwd":"密码"},"code":1}用户或者密码为空返回JSON数据包:
{"msg":"用户或者密码为空","result":{"uname":"用户名","pwd":"密码"},"code":0}用户或者密码错误返回JSON数据包:
{"msg":"用户或者密码错误","result":{"uname":"用户名","pwd":"密码"},"code":0}参数
说明
msg
提示消息
result
返回登录的用户名和密码
code
状态0：登录失败1：登录成功
用户注册接口调用
https://xxx.xxx.xxx:8080/项目命名/vue/userAction_reg.action字段说明类型是否必填uname名字String是pwd密码String是注册返回JSON数据包：
{"msg":"用户注册成功","code":1}用户注册失败返回JSON数据包：
{"msg":"用户注册失败","code":0}参数
说明
msg
提示消息
code
状态码0：失败1：成功
树形菜单调用接口
https://xxx.xxx.xxx:8080/项目命名/vue/treeNodeAction.action返回的json数据表如下：
{"msg":"操作成功","result":[{"treeNodeId":1,"treeNodeName":"系统管理","treeNodeType":1,"url":null,"position":1,"icon":"el-icon-setting","children":[{"treeNodeId":2,"treeNodeName":"用户管理","treeNodeType":2,"url":"/sys/VuexPage1","position":2,"icon":"el-icon-user","children":[]},{"treeNodeId":3,"treeNodeName":"角色管理","treeNodeType":2,"url":"/sys/VuexPage2","position":3,"icon":"","children":[]},{"treeNodeId":4,"treeNodeName":"密码修改","treeNodeType":2,"url":null,"position":4,"icon":null,"children":[]}]},{"treeNodeId":5,"treeNodeName":"论坛管理","treeNodeType":1,"url":null,"position":5,"icon":"el-icon-reading","children":[{"treeNodeId":6,"treeNodeName":"文章管理","treeNodeType":2,"url":"/sys/Articles","position":6,"icon":null,"children":[]}]}],"code":1}参数
说明
msg
提示消息
result
返回树形菜单结果集
code
状态0：失败1：成功
Result树形菜单结果集
参数
说明
treeNodeId
菜单id
treeNodeName
菜单名
treeNodeType
菜单类型1：父菜单2：跳转菜单
url
路由地址
icon
菜单图标
children
子菜单集，如果没有则为一个空json数组
文章查询调用接口
https://xxx.xxx.xxx:8080/项目命名/vue/articleAction_list.action参数
是否必填
说明
page
否
当前页码，默认为1
rows
否
一页展示多少条数据，默认为10
title
否
按文章标题查询
返回json数据包说明：
{"result":[{"id":1,"title":"文章标题","body":"文章内容"],"pageBean":{"page":1,"rows":10,"total":100,}}result结果集
参数
说明
id
文章id
title
文章标题
body
文章内容
pageBean分页对象说明
参数
说明
page
当前页码
rows
一页展示的条数
total
总条数
文章添加调用接口
https://xxx.xxx.xxx:8080/项目命名/vue/articleAction_add.action参数
是否必填
说明
title
是
文章标题
Body
否
文章内容
添加成功返回JSON数据包：
{"msg":"新增成功","result":[],"code":1}添加失败返回JSON数据包：
{"msg":"新增失败","result":[],"code":0}参数
说明
msg
提示消息
code
状态码0：失败1：成功
文章修改调用接口
https://xxx.xxx.xxx:8080/项目命名/vue/articleAction_edit.action参数
是否必须
说明
id
是
文章id
title
否
文章标题
body
否
文章内容
修改成功返回JSON数据包：
{"msg":"修改成功","code":1}修改失败返回JSON数据包：
{"msg":"修改失败","code":0}参数
说明
msg
提示消息
code
状态码0：失败1：成功
文章删除调用接口
https://xxx.xxx.xxx:8080/项目命名/vue/articleAction_del.action参数
是否必须
说明
id
是
文章id
删除成功返回JSON数据包：
{"msg":"删除成功","code":1}删除失败返回JSON数据包：
{"msg":"删除失败","code":0}参数
说明
msg
提示消息
code
状态码0：失败1：成功
谢谢观看！