随时发布：REST API文档的代码仓库中的持续集成与协做

本文主要内容：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的示例测试

您能够测试文档源文件的质量以及是否构建。您还能够检查拼写或语法，但也能够经过人为进行检查。但测试文档的目的是减轻人类审阅者的审查负担，自动化能节省时间，以即可以编写，发布和发布更多文档文件。

1.连接检查

对于许多静态站点生成器，有专门用于检查站点中全部连接的库。例如，在检查像docslikecode.com这样的Jekyll网站上的连接时，Travis CI工做很简单：

#!/usr/bin/env bash

set -e # halt script on error

bundle exec jekyll build

bundle exec htmlproofer ./_site

经过这种类型的测试，人工审阅者没必要花时间点击新补丁中的每一个连接。若是须要更新外部连接，那么这个测试的结果会通知您。若是内部连接因修补程序自己而中断，则系统能够在人为查看修补程序以前修复它。

2.JSON格式

使用REST API文档，请求和响应一般是JSON文件，对于阅读文档的人在将本身的环境与文档进行比较时很是有价值。在读者须要复制和粘贴请求的状况下，正确格式化示例相当重要。在OpenStack中，咱们有一组包含JSON测试器和格式化程序的通用文档工具。经过对传入的修补程序对文档文件运行此测试，读者能够肯定所包含的JSON文件是否格式正确。此外，当它们能够在本地运行简单命令以确保JSON格式正确时，它可使贡献者更容易建立补丁。

3.验证的请求和响应

高级文档测试能够检查文档中包含的示例请求和响应。用查看代码文件相同的方式查看文档文件时，准确性一般是最高值。所以，经过针对正常工做的API端点测试示例，您能够证实这些示例也适用于实际状况。这种类型的验证提供了每次均可用的成功文档示例，由于只有它们经过验证测试，它们才被发布。

4.创建检查

自动化文档测试能够节省读者的时间，由于他们没必要本身构建文档来查看输出。此外您能够测试损坏的连接或不正确格式化的JSON文件的构建。对于任何奇怪的问题，查看源文档和输出文档都颇有帮助。

自动化测试功能除了能减小开发的时间以外，自动化测试还有助于进行项目流程测试，最近由于一直在使用EOLINKER进行API研发管理，所以推荐自动化测试功能，由于它支持UI模式和高级模式，能够实现不一样类型的自动化测试项目，好比登陆验证就能够用UI模式，高级模式则用来测试较为复杂的项目，对比以前效率高了很多，对API自动化测试等方面有兴趣的小伙伴前往了解下哦！ www.eolinker.com

结论

在与代码库相同的仓库中协同处理文档，能够更好地为客户提供服务，不管他们是组织的内部仍是外部。经过将API文档视为代码，您能够找到自动化途径，提升效率，加快文档构建，在文档中构建成功示例。

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

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

原文地址：www.infoq.com/articles/ci…