免费的API文档编写工具

1.具有无可挑剔的品牌选项的免费API文档工具：ReDoc.ly

我们列表的顶部是 ReDoc。作为帮助团队使用 OpenAPI 构建 API 规范的咨询服务，ReDoc 工具功能强大，同时支持 OpenAPI v2 和 OpenAPI v3。

那么为什么它是我们的最爱呢?主要是灵活性。事实上，ReDoc 以四种不同的模式工作：

ReDoc 代码的托管构建： 您只需使用他们提供的 HTML 模板构建一个网页。这将加载实现该工具的 JavaScript，您的任务是为您的 API 规范指定 URL。

ReactJS 组件：它通过 NPM 包交付，并且很容易集成到 React 项目中。

命令行 (CLI) 工具：您可以运行服务器来生成可浏览 API，也可以生成包含可浏览 API 的静态 HTML 文件。

作为 Docker 镜像：一个只是打包 ReDoc 服务器的镜像。

每种模式都为您提供了自定义可浏览文档的主题选项。这使您可以完全控制颜色、字体选择、移动响应和品牌图像。

2.Swagger UI ——OpenAPI的直接后代

当然，当 SmartBear 向公众捐赠 Swagger 规范时，Swagger 团队就是 OpenAPI 的起点。但是，他们仍在开发 Swagger 工具并为商业活动提供服务。提供了很多东西，但我们在这里只看 Swagger UI。

虽然 Swagger UI 提供了很好的结果，但文档有时有点混乱。您可以在多种模式下使用它，但并不总是清楚如何实现每种模式：

一个独立的网页：可以使用 swagger-ui-dist 包。没有文档，但是包有一个 index.html 可以直接使用。这可以用作您网站的示例。

与 Express Web 应用程序集成：可以推断其他 Web 应用程序框架。

ReactJS 组件：使用 SwaggerUIBundle。该组件似乎允许插件扩展 UI，但文档不清楚。

一个 Docker 镜像：提供一个预打包的 Swagger UI 服务器，相对容易使用。

作为通过 Unpkg CDN 的图像：再次，缺乏文档。

3.DapperDox –外观漂亮，但缺乏功能

用于查看 OpenAPI v2 或 v3 规范的开源项目。它有很多有趣的功能，其中之一就是集成用 Markdown 编写的文档。

虽然这是一个很棒的功能，但 DapperDox 有时有点挑剔。我们尝试了几个 OpenAPI v2 示例，它经常给出诸如“错误：GET /v1/pets/{petId} 引用没有标题成员的模型定义”之类的错误，之后服务器就会崩溃。我们发现唯一可以可靠工作的示例是官方 OpenAPI 存储库中的简单 OpenAPI v3 PetStore 演示。

DapperDox 作为从 Go 源代码为特定操作系统编译的二进制文件提供。 它是一个命令行工具，用于解析 OpenAPI 规范，并且是一个提供文档的 Web 服务器。

该DapperDox网站拥有广泛的文档区，这是清晰和易于理解。 除了可浏览的 API 规范和自定义演示之外，它还介绍了构建指南。