文章采集api(一个的API文档是什么？如何正确使用？(组图))

　　文章采集api(一个的API文档是什么？如何正确使用？(组图))

　　对于程序员来说，API 文档对于程序员来说是很熟悉的东西，几乎每天都要和他们打交道。在大多数开发团队中，只要有前后端合作，API文档就会作为两方之间的桥梁存在。API 文档是对后端提供的服务的描述。前端开发人员通常是 API 文档的消费者。下面我从消费者的角度来谈谈什么样的API文档是有用的。

　　什么是 API 文档？

　　简单的说就是对所有API调用和涉及的参数进行了清晰的说明。更具体地说，就是每个API可以做什么，以及API中每个参数的解释，包括它们的类型、格式、可能的值、验证规则，以及它们是否有必要。

　　什么是 API 文档？

　　欢迎页面

　　有些人经常忽视这个页面的重要性。当然，如果是内部项目，欢迎页面有时不是那么重要，但是如果API文档是外部的，比如各个公司的开放平台文档，那么详细的欢迎页面甚至可以决定一个开发者是否是愿意访问您的平台。

　　欢迎页面可以收录的内容：

　　（Spotify 的 API 文档欢迎页面）

　　具有完整上下文的示例

　　想象一个我们阅读 API 文档的场景。我们会像小说一样从头开始阅读吗？大多数情况下不是。一般我们会根据名称直接从API列表跳转到我们需要查看的API，直接读取。因此，对于内容的组织，所有必要的信息和相关的解释都必须收录在每个 API 的解释中。例如，GitHub 的 REST API 文档的 commits 部分，详细给出了每个 API 的部分：

　　常见类型的例子

　　可以使用一些工具直接从项目代码中生成文档示例，例如 api blueprint。这样做的好处是在修改源代码时，文档的内容会同步更新，避免了不及时更新文档的问题。但是，建议不要完全依赖自动化工具。生成内容后，还需要手动补充必要的指令，使文档的内容更容易理解。

　　没有什么比 API 在实际项目中的应用更直观了。真实的示例项目代码可以帮助用户了解各个API的使用方式以及连接方式。通常可以在文档中提供指向示例项目的 GitHub 存储库的链接。如果代码量不大，也可以直接贴在文档中。

　　顾名思义，该方法就是在客户端模块中封装API调用，包括鉴权、配置等过程，用户可以在项目中直接引用调用封装的方法。这种方式可以简化客户端调用API的工作复杂度，但同时会增加API提供者的工作量。更新后端服务时，客户端模块也需要同步更新。例如，GitHub 提供了不同语言的客户端模块。

　　错误相关信息

　　另外，一旦在调试过程中出现错误，详细的错误信息文档可以降低解决错误的难度，应该包括：

　　事实上，能够做到这一点的文档会少得多。GitHub 的 API 文档在这方面更为通用。Context.IO的文档在错误信息方面表现更好，可以作为参考。

　　与全球内容相关的话题

　　这是指任何 API 文档中常见且必要的内容，包括：

　　至于这些部分的内容，会根据后端服务的不同而有所差异。同时，在每个具体的API讲解中，当有与这些内容相关的概念时，可以给出具体章节的链接，方便开发者随时跳转。查看。

　　一些可用性建议

　　API 文档可以提供一些小功能来改善用户体验。比如在代码示例旁边设置了一个复制代码的按钮，方便用户一键复制代码；调用API的代码示例提供多语言支持，用户可以查看不同语言的API调用示例。借助复制功能，可以减少编写重复代码的工作。数量。

　　API 文档是什么样的？

　　一个好的API文档，除了内容合理详尽外，风格和交互方式也应该简单易用。目前的API文档基本都是基于网页展示的。利用网页的显示特性，有一些常用的设计方法。以下是一些适合作为 API 文档呈现元素的最佳实践。

　　只要API文档不是特别大，建议单页展示。在单个页面中查找任何内容（无论是浏览器中的网络搜索还是文档提供的导航）都会非常快，加上页面上的设置，共享一个API记录的位置也非常方便。当然，如果API文档的内容太多，强行在单个页面上会影响页面体验，应该果断拆分文档，但记得要保留每个子页面的全局导航信息，方便用户跳转在每一页上。改变。

　　在使用API​​文档的过程中，由于需要频繁搜索内容，页面固定导航栏是非常有必要的。用户可以随时通过导航栏查找文档内容。

　　既然使用了固定位置的导航栏，那么同时使用多列布局是合乎逻辑的。在宽屏桌面网页上，多栏布局可以很好地组织文档内容，导航、API描述和代码示例可以各占一栏。

　　API文档维护

　　维护 API 文档应该和维护一个独立的项目一样。每次更新都以 pull 分支的形式完成。编辑检查文档内容的正确性和简洁性后，项目成员将对其进行审核。

　　API文档发布后，后期维护同样重要。主要有两个方面：

　　新的和过时的功能。在发布新功能之前，您应该发布文档并确保该文档已经通过标准审核流程。对于过时的旧功能，应从文档中删除它们。同时，建议在相应位置提供过时功能的提示和升级指南，方便使用老功能的开发者进行升级工作。文档的投稿条目应保留在文档页面。如果文档托管在 GitHub 等平台上，则会提供指向存储库的链接，以便每个阅读文档的用户都可以向文档提交 Issue 或 PR。如果文档是闭源的，至少应该有一个地方可以提供反馈。

　　以上是项目开发合作中编写友好API文档的一些想法和建议，欢迎讨论。