租车项目-我们一起来看接口设计文档
接口设计文档，在我看来应该有两种，一种是简约而不失要点的；一种是规范而完善的。两者间的关系，应该是简约版的接口文档随着文档的维护而变得更规范。
在一个项目的初期，接口文档的创建，定义都只是一个大纲一样的东西。随着需要文档的评审结束，项目计划的制定完成，所需的接口逐渐明确时，接口文档的起草就可以开始了。
接口设计文档，有一般的格式，比如起草人，版本号，起草时间，所属公司，文档概要，接口规范，接口说明，接口编号，相应状态码等。不过公司应该都有自己的接口文档模板之类的。
来个总的结构show一下：
起草人：可以是某一个人，也可以是几个人（联合起草人）。起草人是可以说是整个接口文档的总设计师，心中能装下整个构架。最明白里面的输入输出的。
起草时间和所属公司或者部门，这个到没什么好说的，一看也明白。再给张图瞧瞧：
版本号：有组人让以后维护的人知道，这个接口文档的变更，相应的应该有变更记录，这个变更记录可以类似于产品发布的change log一样的东东。初稿敲定后，以后的每一次修改都应该更新版本号，修改时间，修改人。一张图看结构：
文档概要，这个大概说明此文档是做什么用的，涉及到什么内容，以及供哪些人员浏览查看。比如租车项目，该文档是需要满足与合作商家的接口数据交互。所处大环境是公司需要在某一个时间点对外发布一个网上租车应用，需要与其他商家合作。通过接口获取到商家的租车信息，以及提供通知接口，让商家通知租车完成等相关信息。接口文档主要是供两边的开发人员浏览查看，接口文档的内容，应该是双方达成一致的结果。
接口规范与接口说明这一块，应该是这样的：包括文档用到的一些变量的说明，接口交互所用到的协议，如HTTP，WebService，Hessian，Dubbo等，传输的数据格式的定义，如JSON，XML等，以及采用哪种加密方式，采用比较多的MD5，DES，AES等，加密参数等，一些公关的东西。
接口编号：这里其实就是一一对应功能点，按标题来的话，应该还有一个大模块下，分几个小模块，但是编号是按一定格式递增的，方便查询。接口交互时，也可以带上编号，作为一个参数传递。
返回码，起到一个代替文字说明，用编号来标识返回信息，系统根据返回编号信息，来解读相应的文字信息（这个是经过双方协商的，大家也知道这个对于关系）。不过，返回码也分为两种情况的，一种是异常型的，一般接口方，都会统一封装自己的异常信息，作为一个统一的码返回给调用方，并且接口提供方，应该有接口异常日志。第二种情况，就是正常流程需要返回的状态码。
给一种参考：
最后，应该还有一项，接口联系人的联系方式，不然怎么找。
其实，我还见过一种比较好的接口文档方式，并不是World扣扣相传，而是挂在网上，作为HTML浏览，这个对做平台方面的，应该是很有作用的。只是相应的一些测试地址，测试token需要隐匿，这个还是得通过建立合作，沟通之后得到。
