如何写一个合格的API文档

一：为什么要编写API接口文档

API接口文档，是开发途中，让其他协作者共同调试的重要工具，就像操作手册，给你一个物品，你可能不知道怎么使用，但是如果有操作手册，就可以让一个刚拿到物品的人，快速的进行使用物品。同理可得，API接口文档，就是为了方便其他写作者，快速理解、迅速使用，并进行接口调用操作的手册。

接口文档，大家可能在工作途中听到很多笑话，比如：程序猿最恨别人不写接口文档；程序员最不喜欢写接口文档…

其实在矛盾的同时，也体现了接口文档的重要性。

有幸，本人由于经常对接三方系统，收到了很多接口文档，其中的_形式，千奇百怪，各有千秋，有些很标准，有些就难以入目。_

二：常见的文档形式

常见文档有以下几种形式

1. webServer文档形式

• webServer文档一般用于商场或财务系统，一般这类文档包括业务实现逻辑图、Web服务分布描述（它定义了Web服务的接口，如服务名、提供的方法、方法的参数信息）；
• 请求格式一般为POST；
• 数据格式一般为XML；

2.Swagger-UI风格文档

此类文档，可以实现线上接口编辑，自动生成token实现后续接口测试调用，一般都基于RESTFUL接口规范。
此类接口可以直观的看到接口是否可用。
地址：https://teevid.github.io/mwapi/index/