接口文档要如何写

一个简单的接口文档，写完给组长看后，发现漏洞百出。下面总结一下写文档需要注意事项：

封皮

封面最好是本公司规定的封面，有logo，内容标题，版本号，公司名称，文档产生日期。（错误地方在于，文档的标题要和页眉中的标题一致）

修订历史

表格形式较好些。包括，版本，修订说明，修订日期，修订人，审核时间审核人。（我错误的地方在于，表格中其他空白表格没有居中）

接口信息

接口调用方式，是post方式还是get方式，接口地址，别人需要线上的哪个地址就写哪个。（自己提前测试好线上的这个接口，是否有其他问题，千万别犯低级的错误，尤其是某个字母写错）

功能描述

一定要清晰的描述接口功能。（不要遗漏一些细节，比如接口获取的信息不包括哪些哪些要写明白）

接口参数说明

每个参数都要和实际中调用的一样，包括大小写；参数的含义言简意赅的说明；格式，是string
还是int 还是long等格式（例如参数为@RequestParam("appKey") String appKey, @RequestParam("randomId") Integer randomId）；说明部分，说明参数值是需要哪个公司提供，并详细说明参数怎么生成的，例如时间戳，是哪个时间段的；参数是否必填，一些参数是必须要有的，有些是可选参数，一定要注意写清晰。

返回值说明

1、有一个模板返回值，并说明每个返回参数的意义。

2、提供一个真实的调用接口，真实的返回值。

接口调用限制，接口调用安全方面

为了接口安全，我们可以进行md5加密方式，或者自己公司一个特殊的加密过程，只要双方采用一致的加密算法就可以调用接口，保证了接口调用的安全性。

文档全局方面

文档大标题的字体字号一致，小的分标题一致，正文部分字号也要一致。文章整体字的类别一致，我认为微软雅黑字体样式给人感觉比较清晰。文档目录，自动生成的目录会添加些许的修饰，去掉不整齐的部分，得到一个整齐的目录格式。

文档维护

文档在维护的时候，如有修改一定要写上修改日期，修改人，对大的修改要有版本号变更。

好文档标准检验

我认为检验一个文档写的是否好，主要还是在内容方面，内容是否仔细没有疏漏之处。是否发给别人使用的时候，无需沟通就能把接口调通。别人通过成功的把接口调通，这就是一个好文档。

总结

虽然对于敏捷开发来说项目不需要需求，设计，详细设计等文档，但是在和别的公司在调用接口的时候，是一定要总结成文档的，形成接口规范，文档规范。昨天看到微信分享的一篇文档，叫做《教养，就是让别人舒服》，我想在写文档的时候，把自己当做看文档的人，怎么写让别人舒服，我想这就是写文档的“教养”吧。

菜鸟欢迎您能共同讨论~