开源 API 文档生成器

API 提供商通过规范和定义来描述其 API 的功能，例如 OpenAPI/Swagger、RAML、API Blueprint、I/O 文档或 WSDL。API 文档解决方案将这些定义转换为结构化的、易于开发人员使用的 API 文档。

API 文档工具有时根据它们所采用的定义类型来命名，例如，Swagger 从 Swagger 定义生成 API 文档。它们还经常在命名中包含定义，例如 RAML 2 HTML。

使用 SWAGGER/OPENAPI 规范的 API 文档生成器

Swagger 规范是一种描述 RESTful API 的强大定义格式。它映射与 RESTful 接口相关的所有资源和操作，并使 API 的开发和使用变得更加容易。

2015 年，Swagger 标准更名为 Open API。作为领先的API标准，Swagger/OpenAPI 积累了大量使用该规范格式的 API 文档生成器。

Swagge

Swagger是一个用于描述、生成、使用和可视化 RESTful Web 服务的完整框架。

使用 Swagger 生态系统通过 OpenAPI 定义以 JSON 或 YAML 格式创建 API 文档，并使用 Swagger 编辑器将其动态转换为网页中的 API 文档。

API文档将通过Swagger UI显示，它生成一个结构良好且外观美观的交互式API文档界面，允许开发者直接在浏览器中尝试API调用，因此可以发送请求并从真实或模拟服务器获得响应。

使用 Swagger UI 显示的 API 文档示例

Swagger 可以免费使用，并根据Apache 2.0 License获得许可。开发者可以在swagger-api GitHub 帐户下找到所有与 Swagger 相关的公共工具。

许多开源项目和商业供应商提供 Swagger 集成，因此请务必在构建新工具之前查看可用解决方案列表，说不定会找到适合您项目需求的现有解决方案。

作为当今领先的 API 生态系统，Swagger 拥有完善的文档和支持。如果决定使用 Swagger 记录 API，可以在线找到大量资源、教程、示例和帮助。

进一步阅读：

• Tom Johnson 的使用 Swagger 编辑器和 Swagger UI 的 OpenAPI 教程：概述
• OpenAPI 规范，GitHub 上的完整教程

DapperDox

借助开源DapperDox，可以编写可读指南，并将它们与 API 规范一起构成一组有凝聚力的文档的一部分：可以将相关文档注入到呈现的规范页面中。

使用DapperDox创建API文档，将DapperDox指向您的OpenAPI/Swagger规范，使用** GitHub风格的Markdown**添加一些文档内容，然后让DapperDox完成其余工作。

ReDoc

ReDoc使用OpenAPI规范生成具有三面板设计的响应式站点。它从OpenAPI描述字段提取Markdown标题到侧边菜单，并支持深度链接。

ReDoc旨在使部署变得非常简单，提供广泛支持OpenAPI对象，并为嵌套对象提供交互式文档。您可以通过第三方扩展包含代码示例，但它缺乏直接试用文档化API的功能。

可用于验证或检查 OPENAPI 规范的工具

• Speccy：使用此工具，您可以确保您的 OpenAPI 3.0 规范不仅有效而且可用。根据您定义的规则检查规范，然后生成人类可读的文档。Speccy 的目标是成为 OpenAPI 的 rubocop 或 eslint。您还可以通过 Docker 运行它。
• Spectral：是一个开源工具，您可以使用它根据预定义样式指南的规则检查 OpenAPI/AsyncAPI/RAML 描述、Kubernetes 配置、GitHub Actions 等。它还具有 Stoplight Studio 集成，可以用作VS Code 插件。
• openapi-lint VS Code Plugin：此扩展可用于验证和检查 OpenAPI 3.0.x 文档，以及在 OpenAPI 2.0 和 3.0.0 之间进行转换。

使用 RAML 规范的 API 文档生成器

RAML（RESTful API 建模语言）可帮助您管理 RESTful API 从设计到共享的整个生命周期。

RAML 基于广泛使用的标准（例如 YAML 和 JSON）构建，并且与语言中立，具有以下工具：Java、Javascript、.Net、PHP、Python、Ruby 等。

要使用 RAML 创建 API 文档，您可以选择API 控制台或RAML 2 HTML等开源工具。文档可以快速、动态地生成。借助适用于多种语言的解析器，您可以创建自己的自定义文档和交互式脚本，例如 e.Pages 和 Spotify。

RAML 2 HTML

RAML 2 HTML是一个简单的 RAML 到 HTML 文档生成器，具有主题支持，为 Node.js 编写。

使用 RAML 2 HTML 的默认主题显示的 API 文档示例

RAML 2 HTML 附带默认主题，但您可以从 NPM 安装更多主题。例如，要将 RAML 渲染为 Markdown，您可以安装 raml2html-markdown-theme。

RAML API 控制台

使用RAML API 控制台，您可以根据 RAML 规范创建 HTML 文档。它允许浏览 API 文档和在浏览器中测试 API 方法。

您可以通过两种方式包含控制台：直接包含或在 iframe 内包含。

RAML API 控制台显示的 API 文档示例

可用于解析、转换和验证 RAML 规范的其他工具

• API Designer：一个基于 Web 的 RAML 编辑器，具有与浏览器集成的文件系统。
• API Workbench：一个功能齐全的集成开发环境（IDE），用于设计、构建、测试、记录和共享 REST API。它支持 RAML 0.8 和 RAML 1.0。
• RAML Cop：用于验证 RAML 文件的命令行工具。
• RAML Sublime Plugin：Sublime 文本编辑器的语法高亮插件。
• RAML to PDF：从 RAML 生成 PDF 文档的工具。
• SOAP RAML Plugin：SoapUI 的插件，允许您将 RAML 文件导入到 SoapUI 中进行测试。
• 对 Visual Studio Code 的 RAML 支持：VS Code 的 RAML 预览、自动完成、智能感知和语法突出显示实现。

使用 API Blueprint规范的 API 文档生成器

API Blueprint是一种基于 Markdown 的文档格式，用于编写 API 描述和文档。借助 API Blueprint，您可以快速设计和创建原型 API，或记录和测试已部署的 API。

由于其广泛采用，有多种为 API Blueprint 构建的工具。从各种独立工具（例如模拟服务器、文档和测试工具）到功能齐全的 API 生命周期解决方案。

Snowboard

Snowboard是一个 API Blueprint 解析器和渲染器。它提供了一个丰富多彩的默认主题，说明 API 请求类型和响应，还可以与自定义模板一起使用。

使用 Snowboard 显示的 API 文档示例

Aglio

Aglio从 API 蓝图文件渲染 HTML，支持自定义颜色、模板和主题。

使用 Aglio 显示的 API 文档示例（Cyborg 两列主题）

其他免费开源 API 文档生成器

除了上面详细介绍的之外，还有许多针对不同语言和 API 规范的开源 API 文档生成器。以下是简要总结：

• OpenAPI Generator：从 OpenAPI 2.0/3.x 文档生成客户端、服务器和文档。支持许多不同的集成和用例，以及通过选项和自定义模板进行自定义。可以通过 NPM、Docker 或 Homebrew 进行尝试。
• I/O 文档：I/O 文档是 TIBCO Mashery 网络的 API 定义格式，附带 RESTful Web API 的实时交互式文档系统。通过在 JSON 模式中的资源、方法和参数级别定义 API，I/O Docs 将生成 JavaScript 客户端接口。
• Slate：Slate 可帮助通过简洁、直观的设计创建响应式 API 文档。尽管它是用 Ruby 构建的，但当您使用 Slate 编写文档时，您只需使用 Markdown，这使得编辑和理解变得简单。默认情况下，您的 Slate 生成的文档托管在公共 GitHub 存储库中，这使得其他开发人员在发现拼写错误或其他问题时可以轻松地向您的文档发出拉取请求。当然，如果您不想使用 GitHub，您也可以将文档托管在其他地方。
• Whiteboard：一个基于 NodeJS 的项目，始于 Slate。
• apiDoc：RESTful Web API 的内联文档，可根据源代码中的 API 注释创建文档。
• CUUBEZ API Visualizer：基于 Java 的 API 解决方案，用于可视化 RESTful Web API 的文档。该API可视化框架支持业界当前可用的所有基于JAXRS的java REST框架和非JAXRS基于java的REST框架。
• Carte：一个简单的基于 Jekyll 的 API 文档网站。设计为样板文件，用于构建您自己的文档，深受 Swagger 和 I/O 文档的启发。
• Docbox：根据 Markdown 文档内容生成的响应式网站，通过 React 动态更新。

还有一个免费的：

API Docs：虽然不是开源的，但 API Docs 免费提供 OAS (Swagger) 和 RAML 规范的托管公共 API 文档服务。通过StopLight集成，只需支付少量费用即可使用自定义域、主题和分析等功能。

通用开源文档工具

尽管 API 文档生成器非常方便，但它并不是呈现和显示 API 文档的唯一方法。许多通用文档工具也可以完成这项工作。

您可以查看几个文档工具：

• Dexy：Dexy 是一种多用途项目自动化工具，具有许多处理文档的功能。它为您完成重复的部分，从而使创建技术文档变得更加容易。许多开发人员使用它来记录 API，因为与其他开源工具结合使用，Dexy 能够运行示例代码、保存结果、从 API 获取数据以及将文档发布到博客或 wiki。
• Docco：Docco 是一个快速且简单的文档生成器。它会生成一个 HTML 文档，其中显示与代码混合的注释。
• Doxygen：Doxygen 是从带注释的 C++ 源生成文档的事实标准工具，但它还支持其他流行的编程语言，例如 C、Objective-C、C#、PHP、Java、Python、IDL、Fortran、VHDL、Tcl 和在某种程度上 D. 要记录您的 API，请生成在线 HTML 文档浏览器或离线参考手册，并配置 Doxygen 以从源文件中提取代码结构。

我们提到这些工具是为了让您了解如何使用 API 文档的通用文档工具，但如果您想遵循这种方法，还有更多工具可供选择。

比较表

	快速总结	来源（规格）	Live Demo
Swagger	完整的生态系统，大量集成 美观的文档 UI 广泛使用，许多可用资源	Swagger/OpenAPI	Swagger demo
DapperDox	将相关文档直接插入到呈现的规范页面中	OpenAPI、标记	DapperDox demo
ReDoc	轻松部署 对 OpenAPI 对象的广泛支持 交互式、响应式文档	OpenAPI	ReDoc demo
RAML 2 HTML	简单 RAML 到 HTML 文档生成器主题支持	RAML、NodeJSwith	RAML 2 HTML demo
RAML API Console	浏览 API 文档并在浏览器内测试 API 方法	RAML、NodeJS	RAML API Console demo
Snowboard	API Blueprint 渲染器	API Blueprint	Snowboard demo
Aglio	具有许多自定义主题的 API Blueprint 渲染器	API Blueprint	Aglio demo
I/O Docs	I/O 文档规范格式的实时交互式 API 文档系统	I/O 文档 (JSON)	I/O Docs demo
Slate	干净、直观的设计 通过 GitHub 进行 Markdown 协作编写	Markdown（Ruby）	Slate demo
Whiteboard	基于 NodeJS 的 Slate 替代方案	NodeJS	Whiteboard demo
apiDoc	RESTful Web API 的内联文档	NodeJS	apiDoc demo
CuuBEZ API Visualizer	可视化 RESTful Web API 的文档	Java	CuuBEZ API Visualizer GitHub repository
Carte	一个简单的基于 Jekyll 的 API文档网站	Jekyll，YAML	Carte demo
Docbox	从 Markdown 文档内容生成的响应式网站	Markdown	Docbox GitHub repository
API Docs	免费托管 API 文档	OpenAPI、Swagger、RAML	API Docs demo

本文节选自pronovix的博客内容。