Question

如何编写优质的API文档？

Answer 1

在我们平常的工作中，常常要和其他部门进行合作，在这个过程中我们就会用到他们的接口（API），当然我们是不知道他们怎么定义的，比起一遍遍地去问他们，这个时候，国际通用做法，他们会甩过来一个文档给我们，那么既然是人写的东西，那自然是褒贬不一咯，有的部门的文档就写的非常清晰，非常完善，你看了文档之后，基本上不用再去问对面的人，除非出现了大的问题。那么如何去写一个完善的API文档呢？从现实出发，来谈谈我在工作中希望看到的文档有哪些内容吧。

1. 文档用处，这里需要简单的写出，这个文档到底是用来做什么的，目的是什么，适合哪些人看
2. 在使用过程中 有哪些前提。比如要申请什么权限，或者拿到某些授权。诸如这样的，就是一些base condition
3. 文档字段的一些细节。比如接口中需要传过去多少个字段，每个字段的类型，字段的取值范围，字段的含义，字段传输示例。
4. api接口的返回值，返回值的格式要求和3一样写明白含义，并且给出样例返回结果。
5. 接口负责人以及负责人的联系方式，办公地点，这样方便在有问题的时候可以第一时间联系到相关责任人。
6. 一段接口使用的示例，包括请求值和返回值，最好是一段简单的代码，当然伪代码也是可以的。

其实写好一个文档是很困难的，在用词上一定要注意，尽量使用准确的词汇，不要使用可能，或许，大概这种不定的词汇，会给阅读者带来很大的困惑，标准就是可以让使用者简单学会如何快速上手。

Answer 2

在我们平常的工作中，常常要和其他部门进行合作，在这个过程中我们就会用到他们的接口（API），当然我们是不知道他们怎么定义的，比起一遍遍地去问他们，这个时候，国际通用做法，他们会甩过来一个文档给我们，那么既然是人写的东西，那自然是褒贬不一咯，有的部门的文档就写的非常清晰，非常完善，你看了文档之后，基本上不用再去问对面的人，除非出现了大的问题。那么如何去写一个完善的API文档呢？从现实出发，来谈谈我在工作中希望看到的文档有哪些内容吧。

1. 文档用处，这里需要简单的写出，这个文档到底是用来做什么的，目的是什么，适合哪些人看
2. 在使用过程中 有哪些前提。比如要申请什么权限，或者拿到某些授权。诸如这样的，就是一些base condition
3. 文档字段的一些细节。比如接口中需要传过去多少个字段，每个字段的类型，字段的取值范围，字段的含义，字段传输示例。
4. api接口的返回值，返回值的格式要求和3一样写明白含义，并且给出样例返回结果。
5. 接口负责人以及负责人的联系方式，办公地点，这样方便在有问题的时候可以第一时间联系到相关责任人。
6. 一段接口使用的示例，包括请求值和返回值，最好是一段简单的代码，当然伪代码也是可以的。

其实写好一个文档是很困难的，在用词上一定要注意，尽量使用准确的词汇，不要使用可能，或许，大概这种不定的词汇，会给阅读者带来很大的困惑，标准就是可以让使用者简单学会如何快速上手。