接口文档应该如何编写

1.背景介绍

接口：API

API（Application Programming Interface）即应用程序接口。可以认为 API 是一个软件组件或是一个 Web 服务与外界进行的交互的接口。

目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。

从另一个角度来说，API是一套协议，规定了我们与外界的沟通方式：如何发送请求和接收响应。

我对API的理解

API就是把某些功能封装好，方便其他人调用。调用的人只要满足接口暴露给调用者的一些访问规则就能很方便使用这些功能，并且可以不需要知道这些功能的具体实现过程。

什么是接口文档？

在实际项目开发中，web项目是前后端分离开发的，APP开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护。

2.知识剖析

接口分为四部分:

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

2、uri：以/a开头，如果需要登录才能调用的接口(如新增、修改；前台的用户个人信息，资金信息等)后面需要加/u，

即：/a/u；中间一般放表名或者能表达这个接口的单词；get方法，如果是后台通过搜索查询列表，那么以/search结尾，

如果是前台的查询列表，以/list结尾。

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

字段是类的属性；说明是中文释义；类型是属性类型，只有String、Number、Object、Array四种类型；备注是一些解释，或者可以写一下例子，

比如负责json结构的情况，最好写上例子，好让前端能更好理解；是否必填是字段的是否必填。

4、返回参数结构有几种情况：1、如果只返回接口调用成功还是失败（如新增、删除、修改等），则只有一个结构体：

code和message两个参数；2、如果要返回某些参数，则有两个结构体：1是code/mesage/data，2是data里写返回的参数,data是object类型；

3、如果要返回列表，那么有三个结构体，1是code/mesage/data,data是object，里面放置page/size/total/totalPage/list 5个参数，

其中list是Arrary类型，list里放object，object里是具体的参数。

衡量接口（API）设计好和坏的准则

槽糕的API接口各种各样，但是好的API接口对于用户来说必须满足以下几个点：

1.易学习：有完善的文档及提供尽可能多的示例和可copy－paste的代码，像其他设计工作一样，你应该应用最小惊讶原则。

最小惊讶原则(Principle of least astonishment)

最小惊讶原则通常是在用户界面方面引用，但同样适用于编写的代码(优秀程序设计原则之一)。代码应该尽可能减少让读者惊喜。也就是说，

你编写的代码只需按照项目的要求来编写。其他华丽的功能就不必了，以免弄巧成拙。

2.易使用：没有复杂的程序、复杂的细节，易于学习；灵活的API允许按字段排序、可自定义分页、排序和筛选等。一个完整的API意味着被期望的功能都包含在内。

3.难误用：详细的错误提示，有些经验的用户可以直接使用API而不需要阅读文档。

而对于开发人员来说，易阅读：代码的编写只需要一次一次，但是当调试或者修改的时候都需要对代码进行阅读。

易开发：一个最小化的接口是使用尽可能少的类以及尽可能少的类成员。这样使得理解、记忆、调试以及改变API更容易。

3.常见问题

如何合理设计接口？

一、设计原理

1. 深入了解需求:从“客户端-接口-数据库”的层次上看，接口明显扮演着承上启下的角色，一方面要明白接口要什么数据，另一方面要考虑如何

从数据库获取、组织数据。所以如果不了解需求，你就无法正确抽象对象来组织数据给客户端，也无法验证数据库的数据结构能否满足需求。

2.了解数据库结构:既然接口要明白如何从数据库获取、组织数据，就当然要了解数据库结构啦。

3.了解客户端原型:了解原型，其实更多是为了帮助你设计接口时需要提供的数据和结构。

二、设计原则

1.充分理由:不是随便一个功能就要有个接口，也不是随便一个需求就要加个接口。每新建一个接口，就要有充分的理由和考虑，无意义的接口不仅增加了维护的难度，

更重要是对于程序的可控性的大大降低，接口也会十分臃肿。

2.职责明确:一个接口只负责一个业务功能，比如查询会员，但不要在查询会

员的同时还有修改权限等类似的其他业务功能，应该分成两个接口做。

3.高内聚低耦合:一个接口要包含完整的业务功能，而不同接口之间的业务关联要尽可能的小。

4.分析角度明确:设计接口分析的角度要统一明确。否则会造成接口结构的混乱。

5.入参格式统一:所有接口的参数格式要求及风格要统一，不要一个接口参数是逗号分隔，

另一个就是数组;不要一个接口日期参数是x年x月x日风格，另一个就是x-x-x。

6.状态及消息:提供必要的接口调用状态信息。调用是否成功?如果失败，那么失败的原因是什么。这些必要的信息必须要告诉给客户端。

7.控制数据量:一个接口返回不应该包含过多的数据量，过多的数据量不仅处理复杂，

对数据传输的压力也非常大，会导致客户端反应缓慢。过多的数据量很多时候都是接口划分不明确。

三、设计方法

1.数据格式：

接口定义的数据格式必须都经过充分考虑，否则会出现数据转换失败或超出长度等错误。如果无法确定，直接设置成字符串是最合适的。

2.有意义的命名：

无论是接口还是参数，名称都应该是有意义的，让人能看明白的。

5.编码实战

7.参考文献

https://www.zhihu.com/question/52409287/answer/130390641

http://blog.csdn.net/lingshaoxia/article/details/21097839

8.更多讨论

问：有哪些比较好的接口文档编写软件

答：http://rapapi.org

问：mock是啥

答：是一个可以规范返回数据的东西

问：那个返回值里的code有具体规范吗

答：有不同的规范，最重要的是前后端统一

接口文档应该如何编写相关推荐

接口文档编辑工具+接口文档编写
目录接口文档编辑工具接口文档编写补充 GET与POST的区别接口文档编辑工具参考@Lucky锦[接口文档编辑工具] Swagger: 通过固定格式的注释生成文档. 省时省力,不过有点学习成本 ...
【接口文档】Django restful framework中自动生成API文档
Django restful framework中自动生成API文档一.Swagger概述 1.引言当接口开发完成,紧接着需要编写接口文档.传统的接口文档使用Word编写,or一些接口文档管理平台 ...
作为Java开发工程师，如何高效优雅地编写接口文档
作为一名优秀的Java开发工程师,编写接口文档向来是一件很头疼的事情.本来就被bug纠缠的很累了,你还让我干这? 其实,你可以试试ApiPost. ApiPost的定位是Postman+Swagger ...
接口文档编写步骤与格式
接口文档编写步骤与格式 1. 基本步骤梳理需求依据业务写汉字版的接口文档.(可以减少在实际开发过程中的数据库调整) 写接口文档的过程中,会联想到需要上面样的数据. 进而推出数据库设计. 数据库设计 ...
swagger工具编写接口文档
1.什么是swagger2 编写和维护接口文档是每个程序员的职责,根据Swagger2可以快速帮助我们编写最新的API接口文档,再也不用担心开会前仍忙于整理各种资料了,间接提升了团队开发的沟通效率. ...
Go之开发小功能集合（viper获取配置信息，test编写测试单元，用户目录获取，JWT安全校验，字符串去重，Swag在线接口文档，画字符图像工具，Gin模式的选择，iota枚举，promhttp等）
提示: 该链接是go语言小工具: https://www.kancloud.cn/congzaifeng/go_third_party_libraries/467593 Go语言学习全面文档:http ...
如何编写一个好的规范中投证券L2接口文档？
如果你的案例可以直接依靠复制拿来使用,那这个文档就是好文档既然要简单,那就抓住核心:怎么简单怎么来,怎么省时间怎么来如果不知道怎么写,就把案例写的越详细越好.开发时间是非常宝贵的,而接口对接通常都是一 ...
python生成接口文档_使用apiDoc实现python接口文档编写
使用apiDoc实现python接口文档编写 apiDoc的安装 npm install apidoc -g 生成api的终端命令:apidoc -i 代码所在路径-o 生成文件的路径接口文档的编写 ...
接口文档如何编写，接口文档快速生成工具
正规的团队合作或者是项目对接,接口文档是非常重要的,一般接口文档都是通过开发人员写的.一个工整的文档显得是非重要.下面我总结下自己看到的优秀接口文档. 一.背景介绍接口:API API(Applic ...

接口文档应该如何编写

接口文档应该如何编写相关推荐

最新文章

热门文章