共计 3934 个字符，预计需要花费 10 分钟才能阅读完成。
本文主要内容：API 文档提供了预测客户成功的关键路径；在代码附近的文档上进行协作可以更好地检查代码和文档文件，提高自动化效率，并专门针对文档进行质量测试；提供通用文档框架，标准，自动化和工具，以提高团队效率。
编写文档有时候会非常枯燥乏味，但优秀的文档是增加 API 被采用的一个很好的前提。编写出色的文档与编写代码一样需要严谨。随着 API 的质量逐渐成为产品增长的指标，您的文档比以往任何时候都更加重要，优秀的文档很大程度上代表创建了成功的 API。API 定义和文档常常结合在一起，虽然今天的 API 规范越来越多地作为 GitHub 中的代码进行管理，但 API 文档并非如此。所以需要让我们对此进行更改，以便在 GitHub 和相关代码库中编写和管理 API 文档（包括相关网站）的标准。
通过尽可能靠近代码和 API 定义协作编写文档，您可以自动执行文档测试，构建和部署。API 的文档通常构建为网站，因此如果在分段构建期间就可以进行链接检查等测试。这种方法提供了许多好处：经过测试的文档构建；支持连续发布；支持对文档内容和代码的评论；多个输出（包括经过测试的代码示例）；文档的发布管理（如 API 的早期访问版本）或增量更改和添加到发布了 API，并防止代码合并。
文档持续集成 / 交付
对于 REST API 文档，三个框架以网页的形式提供文档输出，其中许多是交互式的。这些是 OpenAPI（Swagger），RESTful API 建模语言（RAML）和 API 蓝图。OpenAPI（以前称为 Swagger）基于 JSON 输出，由于 YAML 是 JSON 的超集，因此您可以交换描述 API 的源文件。RAML 是一种基于 YAML 的语言，用于描述 REST API。API Blueprint 使用 Markdown，也可以遵循 GitHub Flavored Markdown 语法。
许多编程语言都有一个文档框架，可以很好地与代码本身集成。通常，这些是静态站点生成器，例如 Jekyll for Ruby 和 Sphinx for Python。文档的源文件是 Markdown 或 reStructured Text（RST）。使用这些静态站点生成器，您可以创建漂亮的文档站点。事实上，GitHub 上有一系列链接到漂亮的文档网站，其中包括 Stripe API 文档站点和 Basho 文档 – 这些是获得美观和实用程序最高分的示例 API 站点。
由于可以使用脚本转换这些文档源文件和网站配置文件，因此您可以使用与代码相同的构建作业来持续构建文档。通过从静态目录复制平面文件来部署 Jekyll 站点，因此您可以存储脚本以使用其他构建文件在代码存储库中构建站点。您还可以使用简单的链接检查程序在部署站点之前测试任何损坏的链接。HTMLProofer 库是一个为此而编写的 Ruby 库。
GitHub 提供的部署机制称为 GitHub Pages。您可以选择触发文档网站部署。您可以从 gh-pages 分支，主分支自动化构建，或始终从主分支上的 / docs 目录部署文档。虽然您可以部署到自定义域名，但 GitHub 页面的一个限制是您不能直接通过 HTTPS 提供服务，但作为免费服务，它是一个很好的起点。对于生产网站，您可以从 GitHub 部署到具有所需安全要求的云服务器或 VPS。而 GitHub Enterprise 是 GitHub 的内部部署，用于内部部署，提供类似的托管站点功能。
为什么要像代码一样处理文档
当成果已经可以交付给开发人员时，那与开发人员一起写文档会很有效。API 文档任务为处理代码等文档的原因和时间提供了一个很好的示例。特别是在设计 API 或向 API 添加功能时的关键设计点，开发人员可以像文档代码一样贡献文档。
例如，在自动化参考信息时，您可以获得即时性和准确性，并通过在 GitHub，Bitbucket 或 GitLab 等社交编码系统中协作编写来获得贡献，质量和同理心。此外，API 的最大成功指标之一是文档的准确性和有用性。当您的团队处理代码等 API 文档时，以下是一些特定的好处，下面将对此进行更深入的探讨：
1. 协作效率
可以为开发人员和文章协作编写者两个角色提供有价值的信息。开发人员希望为类似于自己的受众撰写文章，为读者提供经验分享。协作编写者有一个特殊的诀窍来组织信息，文笔更好，并以适当的顺序揭示概念和参考信息。如果在同一个存储库中协同工作可以提供沟通的效率，增加教学和被教学的机会。
2. 贡献收益
当没有专门的技术写作团队时，你可以扩大贡献者的数量，即使 API 本身不是公共文档的公共文件。或者，您可以通过在 GitHub 或 Bitbucket 等版本控制系统中提供开源文档存储库，从最终用户自己获得更多贡献。当文档与代码位于同一存储库中时，任何感兴趣的开发人员（包括客户）都可以订阅拉取请求的通知。
3. 跟踪文档中的错误
要获得更高质量的文档，请提供直接在输出页面上报告文档错误的方法。正如莱纳斯定律所述，“给予足够的眼球，所有的错误都是浅薄的”。通过为这些眼球提供报告错误的位置，您可以为文档提供更多类似代码的质量跟踪。此外，通过问题跟踪制定的指标，您可以衡量文档的质量，并确保在需要解决这些错误时可使用指标来判断。
4. 对文档和代码的评论
在查看代码中包含的文档时，审阅者可以在文档不足时阻止对代码的更改。该审查指南为团队提供了使文档具有高质量的能力，即使它们必须与快速变化的代码同步。
将文档源文件放在像 GitHub 这样的开放系统中可以使内容具有开放贡献，类似于开源代码。在 OpenStack 中，大量的开源云项目，文档贡献过程与代码贡献过程相同。编写者和开发人员在访问仅文档存储库（仅代码存储库）时具有相同的协作工具和背景知识。
当您的 API 定义需要一定程度的守门或小心防护时，您还可以考虑将 GitHub Enterprise 用于内部 API 文档。您的团队仍然可以在内部获得协作优势，而无需向全世界打开您的文档和代码。
5. 部署和发布
处理代码等文档时，意识到您正在将构建与部署分离。通过这种方式，您可以对文档的早期草稿进行审核，并且在文档构建部署并发布到网站之前，它都可以随时进行修正。或者，您可以选择不断发布一些文档以跟上代码。例如，您可以选择编写叙述性文档和教程，这些文档和教程会随着每个补丁集添加而不断发布。但对于像 OpenAPI 规范这样的合同文档，只有在考虑在特定版本下发布 API 时，才能部署新文档。
6. 测试和构建文档
通过为评论提供匹配的分段构建和向读者交付的生产构建，您可以确信您对构建的文档的审核满足用户需求。请参阅以下部分中的示例。
docs 的示例测试
您可以测试文档源文件的质量以及是否构建。您还可以检查拼写或语法，但也可以通过人为进行检查。但测试文档的目的是减轻人类审阅者的审查负担，自动化能节省时间，以便可以编写，发布和发布更多文档文件。
链接检查
对于许多静态站点生成器，有专门用于检查站点中所有链接的库。例如，在检查像 docslikecode.com 这样的 Jekyll 网站上的链接时，Travis CI 工作很简单：
#!/usr/bin/env bash
set -e # halt script on error
bundle exec jekyll build
bundle exec htmlproofer ./_site
通过这种类型的测试，人工审阅者不必花时间点击新补丁中的每个链接。如果需要更新外部链接，那么这个测试的结果会通知您。如果内部链接因修补程序本身而中断，则系统可以在人为查看修补程序之前修复它。
JSON 格式
使用 REST API 文档，请求和响应通常是 JSON 文件，对于阅读文档的人在将自己的环境与文档进行比较时非常有价值。在读者需要复制和粘贴请求的情况下，正确格式化示例至关重要。在 OpenStack 中，我们有一组包含 JSON 测试器和格式化程序的通用文档工具。通过对传入的修补程序对文档文件运行此测试，读者可以确定所包含的 JSON 文件是否格式正确。此外，当它们可以在本地运行简单命令以确保 JSON 格式正确时，它可以使贡献者更容易创建补丁。
验证的请求和响应
高级文档测试可以检查文档中包含的示例请求和响应。用查看代码文件相同的方式查看文档文件时，准确性通常是最高值。因此，通过针对正常工作的 API 端点测试示例，您可以证明这些示例也适用于实际情况。这种类型的验证提供了每次都可用的成功文档示例，因为只有它们通过验证测试，它们才被发布。
建立检查
自动化文档测试可以节省读者的时间，因为他们不必自己构建文档来查看输出。此外您可以测试损坏的链接或不正确格式化的 JSON 文件的构建。对于任何奇怪的问题，查看源文档和输出文档都很有帮助。
结论
在与代码库相同的仓库中协同处理文档，可以更好地为客户提供服务，无论他们是组织的内部还是外部。通过将 API 文档视为代码，您可以找到自动化途径，提高效率，加快文档构建，在文档中构建成功示例。
自动化测试功能除了能减少开发的时间之外，自动化测试还有助于进行项目流程测试，最近因为一直在使用 EOLINKER 进行 API 研发管理，因此推荐自动化测试功能，因为它支持 UI 模式和高级模式，可以实现不同类型的自动化测试项目，比如登录验证就可以用 UI 模式，高级模式则用来测试较为复杂的项目，对比之前效率高了不少，对 API 自动化测试等方面有兴趣的小伙伴前往了解下哦！https://www.eolinker.com
作者：Anne Gentle，思科的技术产品经理；
原文标题：Always Be Publishing: Continuous Integration & Collaboration in Code Repositories for REST API Docs；
原文地址：https://www.infoq.com/article…；
