写接口文档的一些注意事项

转载文章，原文如下：

下面总结一下写文档需要注意事项：

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

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

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

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

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

6）返回值说明
1、有一个模板返回值，并说明每个返回参数的意义。
2、提供一个真实的调用接口，真实的返回值。

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

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

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

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

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