选择API接口文档工具的建议

1.选择静态站点生成器

如果您想要强大的控制力来创建您需要的复杂功能(也许您想构建自定义主题或构建具有独特品牌的文档站点)，请使用静态站点生成器，例如Hugo、Sphinx或Jekyll。如果您有严重的文档需求(也许您从 DITA 世界迁移过来并习惯于更强大的工具)，您将需要一个可以深入到您想要的平台。Jekyll、Sphinx 和 Hugo 在平台中提供了这种深度。

当然，这种能力和控制需要更复杂的平台和学习曲线，但您可以从一个现成的主题轻松开始，然后根据需要进入自定义开发。

如果您没有 Web 开发技能并且不想修补主题或其他代码开发，请选择Readme.com或Netlify CMS等解决方案(不过，使用 Netlify CMS，您仍然必须选择一个主题)。自述文件为您的 API 文档站点提供了现成的设计，消除了设计主题和确定托管/部署的需要。这可以为您节省大量时间和精力。

意识到在实施解决方案时，您可能会花费四分之一的时间(在项目时间间隔的几个月内)定制您的主题并处理文档工具。如果您不想在工具上花费太多时间，Readme 是一个不错的选择。

如果您想使用静态站点生成器，您应该选择哪一个——Jekyll、Hugo、Sphinx 或其他一些?Sphinx 具有最面向文档的功能，例如搜索、PDF、交叉引用链接和语义标记。如果这些功能很重要，请考虑 Sphinx。

然而，选择 Jekyll 或 Hugo 而不是 Sphinx 确实有理由，因为他们的社区超出了文档组。Sphinx 被设计为一个文档平台，因此它的受众往往更小众。文档工具几乎从来没有像更通用的 Web 开发工具那样具有社区规模。因此，与 Jekyll 或 Hugo 的权衡是，尽管它们缺乏一些更好的文档功能(交叉引用、搜索、PDF、语义标记)，但从长远来看，它们可能拥有更多的社区和动力。尽管如此，如果您必须为搜索、PDF 和翻译(这些是可行的，但不是开箱即用的)找出解决方案，这可能会让您陷入困境。

标记也是一个考虑因素。如果您已将选择范围缩小到使用 reStructuredText 的 Sphinx 或使用 Markdown 的 Jekyll/Hugo，那么要问的一个问题是贵公司的工程师是否会使用 reStructuredText 进行写作(假设工程师会写作)。如果他们用 reStructuredText 编写，很好，由于reStructuredText的语义优势，Sphinx 可能更适合文档项目。但如果工程师坚持使用 Markdown，那么也许 Jekyll 或 Hugo 会是更好的选择。

2.选择托管和部署平台

在确定要使用的静态站点生成器的范围后，接下来考虑托管和部署选项(提供持续交付)。如果您决定使用 Sphinx，请考虑使用Read the Docs。如果您已决定使用 Jekyll，请探索GitHub Pages、CloudCannon、Netlify或Aerobatic。如果您已决定使用 Hugo，请探索Netlify或Aerobatic。通过使用这些平台之一，您可以减轻维护服务器和部署站点的巨大负担。

通常，在公司内部，工程团队管理和控制服务器基础设施。仅使用内部资源设置和维护您自己的文档服务器可能是一笔相当大的费用和头痛。可能需要数月(如果不是数年)才能让工程师在服务器上为您提供空间，即使他们这样做，它也可能无法提供您需要的一半功能(例如持续交付和 CLI)。这就是为什么我尽可能推荐这些第三方托管和部署选项的原因。

维护自己的服务器不是您想要从事的业务，而这些第三方平台使您能够更有效率。通过服务器的持续交付消除发布的麻烦将简化您的生活。另一方面，如果您有一个工程工具支持小组，并且他们对支持技术文档有足够的带宽和兴趣，则使用内部工具可以促进与您工作中可用的其他工具(例如验证测试)的集成。

如果您的公司更喜欢建立自己的发布渠道，那么在您走这条路之前，请先了解内部解决方案将提供哪些功能。探索这些第三方主机和部署选项的一些优势，并检查内部解决方案是否具有足够的同等性和长期支持。如果你有强大的工程支持，那就太好了，你可能处于一个很好的位置。但如果工程师几乎不给你时间，请考虑第三方解决方案。请参阅案例研究：将工具切换为 docs-as-code，了解我在这条路线上的经验。

如果您没有第三方主机和部署选项的预算，也没有内部工程资源，请考虑部署到AWS S3 存储桶。Jekyll 有一个名为S3_website的插件，可以轻松部署到 S3。它不是持续交付模型，但也不涉及每次要发布时上传整个站点输出。S3_website 插件查看输出中的更改并将这些更改与 S3 上的文件同步。(但是，我承认，一旦您习惯于通过简单地提交到您的存储库来进行持续交付发布，就很难考虑以任何其他方式发布。)

另外，请注意，即使您没有使用 Jekyll，您也可以使用GitHub Pages作为任何静态站点生成器输出的免费发布主机。您只需在本地构建文件，然后将构建的文件推送到支持 GitHub 页面的存储库。使用这种方法，您不会让服务器执行构建过程，但您仍然可以通过命令行处理该过程。在 GitHub 上免费托管您的文档，无论使用何种工具，都特别方便。

3.决定如何解析 OpenAPI 规范

该OpenAPI的规范也可能是你考虑的工具的一个重要因素。您将如何显示所有端点参考文档?与其创建您自己的模板或手动定义这些参考部分，建议您使用可以读取和解析 OpenAPI 的工具作为您的参考文档。没有多少独立的文档工具可以轻松地合并和显示 OpenAPI 规范(目前)，因此也许最好的选择可能是链接到或嵌入Swagger UI与您的文档(假设您没有用于更深入集成的 UX 资源)。