详解接口文档的编写

正规的团队合作或者是项目对接，接口文档是非常重要的，一般接口文档都是通过开发人员写的。一个工整的文档显得是非重要。下面我总结下自己看到的优秀接口文档。

一、背景介绍

接口：API

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

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

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

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

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

二、知识剖析

接口分为四部分:

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类型；

三、接口文档生成工具

国产接口测试和接口文档生成工具apipost，既可以在你开发完接口之后对接口进行测试

还能够前后端实现接口联调，接口开发完善之后还可以生成各种格式的接口文档
分享接口，可以通过分享的接口链接，查看在线的接口文档

还可以下载其他格式的接口文档

如word格式的接口文档