接口定义(接口文档是该前端定义还是后端定义？)

Posted 2023-05-27

篇首语：历史是知识分子文化活动的结果。本文由小常识网(cha138.com)小编为大家整理，主要介绍了接口定义(接口文档是该前端定义还是后端定义？)相关的知识，希望对你有一定的参考价值。

接口定义(接口文档是该前端定义还是后端定义？)

朋友公司新项目，他负责后端开发，因为之前做过全栈的项目，基本前后台思路都门清，就自己把逻辑走通写了api接口，新招了个ios过来说他写的接口不行，就干了一架。

那么接口文档到底是该谁来定义呢？

接口是什么？

API，全称是ApplicationProgramming Interface，即应用程序编程接口，我们日常中习惯简称为“接口”。接口是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件的以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。

接口有什么用？

在平时的开发过程中，前后端经常会进行数据交互，那么在前后端分离的项目中，前端就不用管后台的工作，用api调取数据即可。

接口文档该由谁来写呢？

笔者认为一般接口文档一定是后端来写，只是我们要事先要和前端商量定义，然后再编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护。

通俗一点就是：客户端出接口需求，服务端出接口方案。

为什么要写接口文档？

1、项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发

2、项目维护中或者项目人员更迭，方便后期人员查看、维护

接口规范是什么？

首先接口分为四部分：方法、url、请求参数、返回参数

1、方法:新增(post) 修改(put) 删除(delete) 获取(get)

2、url：uri地址里不允许出现大写字母，如果是两个单词拼接，用/分开

3、请求参数和返回参数，都分为5列：字段、说明、类型、备注、是否必填

4、返回参数结构可以有一个结构体也可以有多个结构体

showDoc

ShowDoc是一个非常适合IT团队的在线API文档、技术文档工具，可以用他来写接口文档。

showdoc且有如下较多亮点1：支持markdown语法（所有的api接口写作现在都支持这个吧，因为他现在太方便了）2：支持多用户协作，你可以在项目下面随意添加多个用户一起完成api文档的写作。3：可以分享并导出项目，生成需要的文档格式如doc，可以离线浏览4：支持响应式，手机电脑同样精彩5：支持项目转让6：支持模版插入7：支持历史版本，你可以把操作恢复到以前的版本。8：showdoc完全开源9：可以部署到自己的服务器10：如果在线使用，可以设置自己的个性域名，也可以对文档进行加密，浏览者需要密码才能访问11：可以通过一个在线测试api的工具，直接生成markdown，你几乎不用写代码就能过所有的参数自动生成

当然还有其他类似的平台也可以满足在线编辑规范接口的平台：eolinker，apidoc，sosoapi等

github.com/eolinkergithub.com/caixw/apidoceolinker，apidoc都是开源的项目有兴趣可了解，可自己搭建测试api和自动生成api文档