如何编写api文档（如何编写api文档文件）

本文目录一览：

• 1、如何编写优质的API文档

• 2、如何优雅的“编写”api接口文档

• 3、如何编写优质的API文档？

如何编写优质的API文档

编写技术文档，是令众多开发者望而生畏的任务之一。它本身是一件费时费力才能做好的工作。可是大多数时候，人们却总是想抄抄捷径，这样做的结果往往非常令人遗憾的，因为优质的技术文档是决定你的项目是否引人关注的重要因素。无论开源产品或面向开发者的产品，均是如此。

实际上，我想说明的是：对于面向开发者的产品来说，其用户体验中最重要的一环并不是什么主页设计、登录过程、或者SDK下载。真正最重要的是产品的API文档！如果没人知道你的产品如何使用，纵使它巧夺天工，又有何用？

如果你是一个专门从事面向开发者产品设计的工程师，那么编写完善的技术文档，就跟你为终端用户提供良好用户体验一样关键。

我见过许多类似的情况，一个项目被草率地扔到GitHub的页面上，仅仅配有两行的readme说明文件。要知道，真正成功的API文档是需要用爱来悉心制作的艺术品。在Parse产品项目里，我们就把自己奉献给了这门艺术！

那么，什么才是制作优秀API文档的关键因素呢？

1. 绝不吝惜使用层次

你的设计文档不应当仅仅直白地列出所有的终端函数和其参数。好的文档应该是一整套有机的系统内容，能指引用户通过文档与API进行交互。退一万步说，你至少让你的文档包含以下几个部分。

参考索引：参考索引应当是一个事无巨细的列表，包含了所有功能函数的繁文缛节。它必须注明所有的数据类型和函数规格。高级开发者要能够拿着它整天当参考书使用。

开发指南：这是介于参考索引和开发教程中间程度的文档。它就仿佛是一篇更加详细的参考索引，阐明了如何使用各种API。

开发教程：开发教程会更加具体地阐述如何使用API，并着重介绍其中的一部分功能。如果能提供可编译运行的源代码，那就再好不过了。

在Parse项目里，我们做到了上述所有三个部分。目前我们正在努力编制更多的开发教程。

另外一个此方面优秀的范例是Stripe’s API() 。这个产品的文档包括一个很棒的《hybrid guide and reference》，以及一套开发教程。《GitHub API参考》也经过了良好的设计。

2. 不要在例子中包含抽象概念

你可以争辩说，我的API本身就是个抽象体, 抽象就是它的特点。然而，当你在教会开发者如何使用的过程中，还是能不抽象就不抽象比较好。

在你的文档中尽可能地举现实中的例子吧。没有哪个开发者会抱怨你举例太多的。实际上，这种做法能显著地缩短开发者理解你产品的时间。对此，我们的网站里甚至给出一个代码样例加以解释。

3. 减少点击次数

开发者痛恨点击鼠标，这已经不是什么秘密了。千万别把你的文档分散在数以万计的页面当中。尽量把相关的主题都放到一个页面里。

我们非常赞成使用“单页面大指南”的组织形式（链接），这种形式不仅能让用户纵览全局，仅仅通过一个导航栏就能进入他们感兴趣的任意主题，另外还有一个好处是：用户在进行搜索的时候，仅仅搜索当前页面，就能涵盖查找所有的内容。

在这个方面的一个优秀范例是ckbone.js documentation，只要你有个鼠标，一切尽在掌握。

4. 包含适当的快速指南

万事开头难，开发者学习一套全新的API，不得不重新适应其全新的思维方式，学习代价高昂。对于这个问题的解决办法是：通过快速指南来引导开发者。

快速指南的目的是让用户用最小的代价学习如何利用你提供的API干一些小事。仅此而已。一旦用户完成了快速指南，他们就对自己有了信心，并能向更加深入的主题迈进。

举个例子，我们的快速指南能让用户下载SDK以及在平台上存储一个对象。为此，我们甚至做了一个按钮，来让用户测试他们是否正确地完成了快速指南。这能提升用户的信心，以鼓励他们学习我们产品其他的部分。

5. 支持多种编程语言

我们生活在一个多语言的世界。如果可能的话，为你的API提供各种编程语言版本的样例程序，只要的API支持这些语言。多数时候，多语言的工作都是由客户端库来完成的。要知道，开发者要想掌握一套API，离开他们熟悉的编程语言，是很难想象的。

MailGun’s API为此做出了良好的榜样。它提供了curl,Ruby,Python,Java,C#和PHP等多个版本供开发者选择。

6. 绝不放过任何边界情况

使用API开发应用，所能遭遇的最糟糕的情况，莫过于你发现了一个文档中没有提到的错误。如果你遇到这种情况，就意味着你不能确认究竟是你的程序出了错，还是你对API的理解出了错。

因此，参考索引中必须包含每种假设可能造成的边界情况，不论是显示的还是隐式的。花点儿时间在这个上面，绝对能起到事半功倍的效果。

7. 提供样例应用

在学习结束的时候，开发者希望能看到关于项目产品应用的大致蓝图。达到这一目的最好的办法，莫过于提供可运行的样例应用。我发现，应用程序代码是将API运行机理和系统整合融会贯通最好的办法。

sample code in Apple’s iOS Developer Library 则是这方面做得很好的，它包含了详尽的iOS样例程序，并按主题一一分类。

8. 加入人性化的因素

阅读技术文档枯燥乏味，自然不像坐过山车那样紧张刺激。不过，你至少可以通过加入一些人性化的因素，或者开开玩笑。给你的例子中的变量其一些好玩儿的名字吧，别老是把函数名称叫什么foo之类的，好让你的读者有焕然一新的感觉。

至少，这可以保证你的读者不会读着读着就睡过去。

结论：

若要想深入人心，一个良好的设计文档必不可少。然而，设计一个好文档是需要大量投入才能形成的。但是，这些投入是值得的，因为它的意义和产品本身同等重要。

编写良好文档的另一半诀窍，是要从产品开发的初始阶段就朝着这个方向努力。不过，这就不是本文讨论的范畴了。

如何优雅的“编写”api接口文档

1. 拼写要准确

接口函数一旦发布就不能改了，要保持兼容性，拼写错误也不能改了，所以要仔细检查拼写，否则会被同行嘲笑很多年。

著名悲剧：unix 的 creat

2. 不仅是英文单词不要拼错，时态也不要错。

比如：

返回bool的判断函数，单数要用 is 复数要用are，这样你的命名就和文档中的描述保持了一致性。

表示状态的变量或者函数要注意时态，比如 onXxxxChanged 表示xxx已经变化了，isConnecting表示正在连接。

正确的时态可以给使用者传递更丰富的信息。

3. 函数最好是动宾结构

动宾结构就是  doSomething，这样的函数命名含义明确

比如： openFile, allocBuffer, setName

如果这个函数的动词宾语就是这个对象本身，那么可以省略掉宾语

4. 属性命名最好是定语+名词

比如 fileName, maxSize, textColor

5. 不要用生僻单词，这不是秀英语的地方，也不要用汉语拼音

比如：rendezvous，估计大多数人要去查词典才知道什么意思，这个词源自法语，是约会的意思。

Symbian OS里有个用它命名的函数，开发Symbian的是英国人，也许人家觉得很平常吧，反正我是查了词典才知道的。

6. 不要自己发明缩写

除非是约定俗成已经被广泛使用的缩写，否则老老实实用完整拼写。

坏例子:  count-cnt, manager-mngr password-pw button-btn

现代的IDE都有很好的自动完成功能，名字长一点没关系的，可读性更重要。

7. 保持方法的对称性，有些方法一旦出现就应该是成对的，

比如 有open就要有close，有alloc就要有free，有add就要有remove，这些单词基本是固定搭配的，使用者就很容易理解。

如果 open对应clear就有点让人困惑了。

如何编写优质的API文档？

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

文档用处，这里需要简单的写出，这个文档到底是用来做什么的，目的是什么，适合哪些人看

在使用过程中 有哪些前提。比如要申请什么权限，或者拿到某些授权。诸如这样的，就是一些base condition

文档字段的一些细节。比如接口中需要传过去多少个字段，每个字段的类型，字段的取值范围，字段的含义，字段传输示例。

api接口的返回值，返回值的格式要求和3一样写明白含义，并且给出样例返回结果。

接口负责人以及负责人的联系方式，办公地点，这样方便在有问题的时候可以第一时间联系到相关责任人。

一段接口使用的示例，包括请求值和返回值，最好是一段简单的代码，当然伪代码也是可以的。

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

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。