本文主要介绍以下的内容：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文档视为代码，您可以找到自动化途径，提高效率，加快文档构建，在文档中构建成功示例。

作者：Anne Gentle，思科的技术产品经理；

原文标题：Always Be Publishing: Continuous Integration & Collaboration in Code Repositories for REST API Docs；

原文地址：https://www.infoq.com/articles/ci-rest-docs/?useSponsorshipSuggestions=true；