接口文档设计

接口文档设计

做一个好点的接口文档，就需要像文章一样显而易见，需要有封面，目录，概述，接口信息（接口规范，请求类型，content-type,协议格式，功能说明，接口描述，请求内容，响应内容，示例），时序图，注意事项，看完这些会发现排版和文章的排版差不多。
整体效果

1.封面

就如同论文的封面一样，起到一个比较官方的效果，你可以在这文档封面加上你们公司的标志。

2.目录

设置一个目录能够让人清楚文档的主要构成，这里的案例图片与上面不同，只做参考

3.概要（概述）

概述该文档的用途，设计该文档的目的，双方对于这个接口文档的要求，只要能够用简洁的语言去概述就可以了

4.接口信息

对于这个接口信息包含了很多的内容，比如接口规范，请求类型，content-type,协议格式，功能说明，接口描述，请求内容，响应内容，示例。
这些接口信息才是文档主要的内容，相信大家都应该知道接口的这些信息，所以具体需要什么可以做删减


在做这一部分的时候我们响应的信息必须保持一致，这样对于成功还是失败响应，对于我们来进行数据的赋值都不会造成影响。

5.时序图

对于时序图是为了帮助我们对于接口运用的梳理，同时也可以让对方了解这个接口的使用地方。本案例只做参考

6.注意事项

这个就相当于我们对接口中某些字段的定义规范，比如时间不能跨年，最大的连接数是多少等等。这个是需要根据你的项目规范来的。
注意:在写这个文档的时候，我们一定要主要用词正确，不要来个同音字，这样文档就显得不太严谨。