接口文档书写规范

封皮

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

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

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

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

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

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

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


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

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

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

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

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