随时发布：RESTAPI文档代码库持续集成协同，提升自动化效率，专门针对文档进行质量测试；提供通用的文档框架、标准、自动化和工具来提高团队效率。编写文档有时会很乏味，但良好的文档是提高API采用率的重要先决条件。编写出色的文档需要与编写代码一样严谨。随着API的质量越来越成为产品增长的指标，您的文档比以往任何时候都更加重要，而出色的文档是创建成功API的重要组成部分。API定义和文档通常结合在一起，虽然如今API规范越来越多地作为代码在GitHub中进行管理，但API文档却并非如此。因此，让我们将其更改为在GitHub和相关代码存储库中编写和管理API文档（包括相关网站）的标准。通过协作编写尽可能接近代码和API定义的文档，您可以自动化文档测试、构建和部署。API的文档通常构建为网站，因此可以在构建段期间进行链接检查等测试。这种方法有很多好处：经过测试的文档构建；支持持续发布；支持对文档内容和代码的评论；多个输出（包括测试代码示例）；文档的发布管理（例如API的早期访问版本）或对已发布API的增量更改和添加，并防止代码合并。文档持续集成/交付对于RESTAPI文档，三个框架以网页形式提供文档输出，其中许多是交互式的。它们是OpenAPI(Swagger)、RESTfulAPI建模语言(RAML)和API蓝图。OpenAPI（以前称为Swagger）基于JSON输出，并且由于YAML是JSON的超集，您可以交换描述API的源文件。RAML是一种基于YAML的语言，用于描述RESTAPI。APIBlueprint使用Markdown，也可以遵循GitHubFlavoredMarkdown语法。许多编程语言都有一个与代码本身很好集成的文档框架。通常这些是静态站点生成器，例如用于Ruby的Jekyll和用于Python的Sphinx。文档的源文件是Markdown或重组文本(RST)。使用这些静态站点生成器，您可以创建漂亮的文档站点。事实上，GitHub有一系列指向精美文档站点的链接，包括StripeAPI文档站点和Basho文档——这些是在美观和实用性方面获得最高分的示例API站点。由于这些文档源文件和网站配置文件可以使用脚本进行转换，因此您可以使用与您的代码相同的构建作业来持续构建您的文档。Jekyll站点是通过从静态目录复制平面文件来部署的，因此您可以存储脚本以使用其他构建文件在代码存储库中构建站点。在部署站点之前，您还可以使用简单的链接检查器来测试是否存在任何断开的链接。HTMLProofer库是为此目的编写的Ruby库。GitHub提供的部署机制称为GitHubPages。您可以选择触发文档站点部署。您可以从gh-pages分支、master分支自动构建，或者始终从master分支上的/docs目录部署文档。虽然您可以部署到自定义域名，但GitHubPages的一个限制是您不能直接通过HTTPS提供它，但作为一项免费服务，它是一个很好的起点。对于生产网站，您可以从GitHub部署到具有所需安全要求的云服务器或VPS。而GitHubEnterprise是GitHub的本地部署，提供类似的托管站点功能。为什么像对待代码一样对待文档当产品已经可以交付给开发人员时，与开发人员一起编写文档会很有效。API文档任务提供了一个很好的例子，说明为什么以及何时处理代码等文档。特别是在设计API或向API添加功能时的关键设计点，开发人员可以像编写代码一样贡献文档。例如，您在自动化引用时获得即时性和准确性，并通过在GitHub、Bitbucket或GitLab等社交编码系统中的协作写作获得贡献、质量和同理心。此外，API最成功的指标之一是文档的准确性和实用性。当您的团队处理API文档（如代码）时，以下是一些具体的好处，下面将对此进行更深入的探讨：1.协作效率可以为开发人员和文章合著者的角色提供有价值的信息。开发人员希望为与他们自己相似的读者写作，让读者分享他们的经验。协作作者具有组织信息、更好地写作以及按正确顺序揭示概念和参考的特殊诀窍。在同一个存储库中一起工作可以提高沟通效率并增加教授和被教授的机会。2.贡献收益当没有专门的技术写作团队时，可以扩大贡献者的数量，即使API本身不是公开文档的公开文档。或者，您可以通过在GitHub或Bitbucket等版本控制系统中提供您的开源文档存储库，从最终用户那里获得更多贡献。当文档与代码位于同一存储库中时，任何感兴趣的开发人员（包括客户）都可以订阅以接收拉取请求通知。3.跟踪文档中的错误对于更高质量的文档，提供一种直接在输出页面上报告文档错误的方法。正如Linus法则所说，“给予足够的眼球，所有的错误都会变得浅薄”。通过给这些眼球一个报告错误的地方，您为文档提供了一个更像代码的质量轨道。此外，通过问题跟踪开发的指标，您可以衡量文档的质量，并确保在需要解决这些错误时指标可用。4.文档和代码的注释在查看代码中包含的文档时，当文档不充分时，审阅者可以防止对代码进行更改。本审查指南为团队提供了制作高质量文档的能力，即使它们必须与快速变化的代码保持同步。将文档源文件放在像GitHub这样的开放系统中可以使内容开放供贡献，类似于开放源代码。在OpenStack中，对于大量的开源云项目，文档贡献过程与代码贡献过程是一样的。在访问纯文档存储库（纯代码存储库）时，编写者和开发人员具有相同的协作工具和背景知识。当您的API定义需要某种程度的守门或小心保护时，您还可以考虑使用GitHubEnterprise来获取内部API文档。您的团队仍然可以从内部协作中获益，而无需向全世界开放您的文档和代码。5.在部署和发布处理代码等文档时，要意识到你是在将构建和部署分开。这样，您可以查看文档的早期草稿，并且可以在构建、部署和发布到您的网站之前随时对其进行更正。或者，您可以选择继续发布一些文档以跟上代码。例如，您可以选择编写随着每个补丁集的添加而随时间发布的叙述性文档和教程。但对于像OpenAPI规范这样的合约文档，只有在考虑发布特定版本下的API时，才应该部署新文档。6.测试和构建文档通过为审阅和交付给读者的生产构建提供匹配的暂存构建，您可以确信您对构建文档的审阅满足用户需求。请参阅以下部分中的示例。文档示例测试您可以测试文档源文件的质量以及它们是否构建。您还可以检查拼写或语法，但也可以由人工来完成。但测试文档的目的是为了减轻人类审阅者的审阅负担，自动化节省了时间，以便可以编写、发布和发布更多的文档文件。链接检查对于许多静态站点生成器，都有专门用于检查站点中所有链接的库。例如，当检查docslikecode.com等Jekyll网站上的链接时，TravisCI的工作很简单：#!/usr/bin/envbashset-e#haltscriptonerrorbundleexecjekyllbuildbundleexechtmlproofer./_site通过这种类型的测试，人类审阅者不必花时间点击新补丁中的每个链接。此测试的结果将通知您是否需要更新外部链接。如果内部链接被补丁本身破坏了，系统可以在人类查看补丁之前修复它。JSON格式使用RESTAPI文档，请求和响应通常是JSON文件，这对于阅读文档的人在将自己的环境与文档进行比较时非常有价值。在读者需要复制和粘贴请求的情况下，正确格式化示例至关重要。在OpenStack中，我们有一组通用的文档工具，包括JSON测试器和格式化器。通过对传入的修补文档文件运行此测试，读者可以确定包含的JSON文件是否格式正确。此外，当贡献者可以在本地运行简单的命令以确保JSON格式正确时，他们可以更轻松地创建补丁。经过验证的请求和响应高级文档测试可以检查文档中包含的示例请求和响应。当您以与查看代码文件相同的方式查看文档文件时，准确性通常最高。因此，通过针对有效的API端点测试示例，您可以证明这些示例在实际情况下也有效。这种类型的验证提供了每次都可用的成功文档示例，因为它们在通过验证测试之前不会发布。构建检查自动化的文档测试可以节省读者的时间，因为他们不必自己构建文档来查看输出。此外，您可以测试构建是否存在断开的链接或格式不正确的JSON文件。对于任何异常情况，查看源和输出文档会很有帮助。结论在与代码库相同的存储库中协作处理文档可以更好地为客户服务，无论他们是组织内部的还是外部的。通过将API文档视为代码，您可以找到自动化、提高效率、加速文档编制以及在文档中构建成功示例的方法。除了减少开发时间，自动化测试功能也有助于项目过程测试。最近因为一直在用EOLINKER做API开发管理，推荐自动化测试功能，因为它支持UI模式和高级模式。实现不同类型的自动化测试项目。例如，UI模式可以用于登录验证，高级模式用于测试更复杂的项目。与之前的相比，效率要高很多。对API自动化测试等方面感兴趣的朋友去了解更多哦！https://www.eolinker.com作者：AnneGentle，思科技术产品经理；原标题：AlwaysBePublishing:ContinuousIntegration&CollaborationinCodeRepositoriesforRESTAPIDocs；原文地址：https://www.infoq。com/文章...；
