使用这些 API 文档工具创建漂亮的 API 文档

一份结构合理、文笔优美的 API 文档可以解释如何有效使用 API 并轻松集成它，这对开发人员大有帮助。

这背后的原因是，无论 API 在创建和扩展软件服务方面有多好，如果开发人员无法理解它的工作原理，它就可能无法使用。

此外，开发人员是严谨的、善于分析的，会通过 API 解决关键问题。因此，迎合他们有时会成为一件棘手的事情。

这就是需要 API 文档的地方。

那么，让我们探索一些关于 API 文档的事情，以及它如何提供帮助。

API 文档是什么？

API 文档指的是技术内容，其中包含有关 API 如何工作、其功能以及如何使用的明确说明。 它可以由技术撰稿人编写，人类和机器都可以阅读。

编制 API 文档的目的是

• 作为一个精确的参考源，能够详尽地描述 API。

• 作为一个教学工具和指南，帮助用户熟悉和使用 API。

一本全面的手册，以结构化的布局包含使用特定 API 所需的全部信息，如函数、参数、返回类型、类等。 文件还包括支持信息的示例和教程。

应用程序接口（API）文档必须便于想要解决某个问题的用户或开发人员消化。优秀 API 文档的要素包括:

• 启动 API 的快速指南

• 认证数据 API

• 调用说明

•  请求示例以及错误信息、响应说明等

•  JavaScript、Java、Python、PHP 和其他编程语言的代码示例

• 如果有，SDK 示例可解释用户如何访问所有资源

API 文档为何重要？

文档是良好用户体验的基础。 需要编写完善的 API 文档，以消除用户的困难，使集成更加顺畅，从而快速进入开发阶段。 如果您投入资源和时间来创建高质量、可读性强的 API 文档，您将获得很多优势：

提高认识

使用产品或服务的人越多，网络效应就越明显。 事实上，那些对您的产品感到满意的人会成为您的应用程序接口的最大拥护者。 因此，如果文档编写得当，语言简单易懂，就能提高 API 的知名度。

提高采用率

良好的文档可促进应用程序接口的广泛采用。 这背后的原因是，用户可能会采用他们喜欢使用的产品或服务，这也适用于您的应用程序接口。 如果您能为他们提供有价值的文档，就能促进 API 的发展和采用。

节省支持费用和时间

没有文档或文档不完善会给用户造成混乱，因为他们会对工作感到困惑。 但是，如果您提供了详尽的文档，并对所有内容都进行了详细说明，就能帮助用户快速上手 API，而不会出现任何混乱。 这不仅为用户节省了时间和挫折感，对您来说也是如此，因为您可以通过支持电话或电子邮件为用户节省无数的时间。

如何创建 API 文档？

您可以通过多种方式（手动和自动）开始编写 API 文档。 您可以将整个过程自动化，这将使您的团队变得更轻松、更省时。

因此，请查看以下服务，创建令人惊叹的 API 文档，为用户提供帮助。

Slate

Slate 是一款出色的工具，可帮助你创建响应迅速、智能且美观的 API 文档。 它的设计简洁直观，灵感来自 PayPal 和 Stripe 的 API 文档。 它将文档放在左侧，编码示例放在右侧，看起来非常酷，在智能手机、平板电脑和印刷品上都能阅读。

有了 Slate，你就不必在无穷无尽的页面中搜索信息了，因为它将所有内容都放在一个页面上，而不会影响链接性。 当有人滚动浏览时，哈希值会更新到最靠近的页眉，因此链接到文档中的某个特定点毫无压力。

这里的所有内容都是用 Markdown 写成的，包括代码块，让你更容易编辑和更清楚地理解。 通过 Slate，你可以用不同的语言编写代码，并在代码块的顶部指定其名称。

Slate 允许对 100 多种语言进行独特的语法高亮显示，而无需对其进行配置。 它还能让你在页面最左侧添加一个可平滑滚动的自动内容表。 对于较大的文档，Slate 也能提供出色的性能。

Slate 生成的 API 文档默认托管在 GitHub 上。 这意味着你可以免费托管 GitHub 页面上的所有文档。

Slate 还为阿拉伯语、希伯来语、波斯语等语言提供 RTL（右至左）支持。 按下绿色按钮–“使用此模板”，然后按照给出的说明操作，即可轻松开始使用 Slate。

Document360

通过 Document360，您可以将 API 文档转化为面向开发人员的交互式文档中心。 开发人员可以在门户网站上使用 “Try-it “功能测试 API，并创建完全自定义的 API 文档。 它支持 OpenAPI 2.0 和 3.0，配有用户友好型编辑器，可以创建工作流程，强大的人工智能搜索功能可在数秒内找到相关的 API 端点。

Document360 提供了一种快速简便的解决方案，用于设计适合技术和非技术受众的有吸引力的 API 文档。 只要 OpenAPI 规范文件发生变化，它就会立即更新您的 API 文档。 它可以从一个地方管理多个 API 定义和版本；用户可以发表评论、提出修改建议并进行实时协作。

使用 Document360，您可以将产品知识库和 API 文档合并为一个中心枢纽，用户可以在其中创建协作文档。

NelmioApiDocBundle

使用 NelmioApiDocBundle 为应用程序接口生成美观的文档。 该工具包支持 PHP、Twig、CSS 等语言。 通过 NelmioApiDocBundle，您可以为您的 API 生成 OpenAPI 格式第 2 版的文档，并提供一个沙盒来对您的 API 进行交互式实验。

该捆绑包支持 PHP 注释、Swagger-PHP 注释、Symfony 路由需求和 FOSRestBundle 注释。 对于模型，NelmioApiDocBundle 支持 JMS 序列化器、Symfony 序列化器、willdurand/Hateoas 库和 Symfony 表单。

Swagger

如果有 Swagger 在身边，就不用再手工编写 API 文档了。 它提供了一系列令人印象深刻的解决方案，用于创建和可视化 API 文档，以及维护这些文档，使它们随着 API 的发展而不断更新。

您可以根据 API 定义自动生成文档。 如果您当前的 API 不包含定义，他们会提供开源的 Swagger Inflector，这样您甚至可以在运行时生成 OpenAPI 定义。 为了加快整个过程，您可以使用 Swagger Inspector 自动为端点创建 OpenAPI 文件。

您可以使用 SwaggerHub 的版本系统维护文档的多个版本。

根据标准规范对 API 进行规模化设计和建模，并使用任意语言为 API 构建可重复使用的稳定代码。 使用 Swagger，您可以利用其交互式文档流程提升开发人员的体验，执行功能测试而无需开销，并为 API 架构设置和执行风格指南。

ReadMe

ReadMe 提供了一种生成和管理交互式精美 API 文档的简便方法。 您可以轻松地在文档中直接加入 API 密钥，自动生成代码示例，并调用实际的 APU，而不会出现任何混乱。

通过回答您在支持论坛上看到的问题，允许消费者提出一些编辑建议，并让每个人都能及时了解更改情况，从而建立一个强大的社区。 同步 Swagger 文件，合并建议的编辑内容，使用编辑器更新内容，确保您的文档始终处于更新状态。

ReadMe 允许你拖放东西；你还可以通过 CSS 自定义一切。 Markdown 编辑器、Swagger 文件导入和主题生成器是 ReadMe 受人喜爱的部分功能。

它甚至允许用户进行 API 调用，然后复制粘贴实际代码示例。 此外，API 日志、API 定义、API Playground 和动态代码片段等功能还能让你制作参考指南。

ReadMe 使您与团队的协作更具互动性，因为他们可以使用版本管理快速提出编辑建议，以保持整洁。 通过论坛式支持收集客户反馈，并认真采取行动，从而提供出色的客户支持。

Widdershins

Widdershins可帮助您从 OpenAPI 3.0、Semoasa、Swagger 2.0 和 AsyncAPI 1.x 定义中创建文档。 最新版本中引入了一些新变化，包括用 “许诺”（Promises）代替回调（callbacks），以及直接输出 HTML 和 ReSpec 格式的选项。

Widdershins 使用模板来创建 Markdown 输出，你可以自定义这些模板或将它们复制到特定文件夹。

Postman

如果你呼吸过空气污染指数（API），就不太可能没听过邮差的声音。

Postman 的 API 文档是您生成连机器都能很好阅读的文档的不错选择。 它还能在每次更改时实时自动更新 API，并让您轻松快速地发布文档。

Postman 可以自动提取您的整个示例请求、代码片段、头文件等，以机器可读的说明和动态示例填充文档。 因此，您可以轻松地与任何人共享应用程序接口。

在文档或网站中嵌入 “在 Postman 中运行 “按钮，即可在几秒钟内共享所有文档集。 这样，任何人只需点击一下即可导入文档。 让开发人员、产品经理、测试人员等任何人都能使用您的文档，从而更广泛地采用 API。

Postman 的评论功能可帮助您的团队通过代码审查和评论分享反馈意见。 轻松整理所有更改，并将错误通知团队，从而向用户展示准确、最佳版本的文档。

ReDoc

ReDoc 是一款由 OpenAPI 或 Swagger 生成的 API 参考文档工具。 它便于部署，可将文档捆绑到零依赖的 HTML 文件中。

ReDoc 提供服务器端渲染，并支持 OpenAPI 2.0 版本的功能，包括判别器。 它还支持 OpenAPI 3.0、代码示例以及具有菜单或滚动同步功能的响应式三面板设计。 你甚至还可以享受嵌套对象的交互式整洁文档。

ReDoc 利用标记符标题。 它可通过侧边菜单中的供应商扩展功能实现深度链接和高级分组。

apiDoc

apiDoc 可让您在源代码中轻松创建 API 注释文档。 它可以灵活地为 API 附加版本号，并帮助您跟踪不同版本之间的变更。

兼容的编程语言有 PHP、Java、JavaScript、Go、C 等。 它支持 GRUNT 模块，并包含一个使用 jQuery、Bootstrap、Handlebars 和 RequireJS 的默认模板。 此外，生成 apiDoc 的默认模板还支持 API 版本管理，并可比较不同版本之间的变化。

Stoplight

如果你拥有 Stoplight，就能消除文档方面的所有压力。 它可以帮助你创建令人惊叹的 API 文档，即使是微不足道的工作。

因此，通过从 OpenAPI 文件自动生成文档，不断为外部和内部消费者提供最佳的开发人员体验。 它包括代码示例、markdown 指南、自定义品牌选项、API 目录和强大的搜索功能。

通过发布具有吸引力的文档、代码示例和教程，使其始终保持最新和同步，从而扩大采用范围并缩短集成时间。 通过为开发人员提供 Java、Curl、Ruby、Python 等编程语言的代码示例，为他们提供帮助。 您可以使用其丰富的标记符嵌入试用函数和 JSON 模式。

利用权限和细粒度角色，将公共和私人文档托管在一个地方。 您还可以建立自己的开发人员中心，在多功能主题选项的帮助下与您的品牌相得益彰。 其强大而广泛的搜索功能允许开发人员查找模式、参考文档和端点。

总之

API 文档的作用就是改善用户体验。 因此，开发一个出色的 API 非常重要，而创建可读的高质量文档来解释其用法也非常重要。 因此，在上述服务的帮助下，通过自动完成创建 API 文档的整个过程来节省您的时间和资源。

原文链接：Create Beautiful API Documentation with these Tools

编译：幂简集成