API技术作家如何搭建设置测试环境

测试您的API文档的第一步是设置测试环境。没有这个测试环境，将很难在测试您的指令方面取得任何进展。

目录

各种测试环境

您设置的测试环境取决于您的产品和公司。在以下各节中，我将说明针对不同方案的测试设置详细信息：

在测试服务器上进行测试

测试API的最简单方法是向配置API服务的测试服务器发出请求。质量检查通常可以帮助您访问测试服务器。使用测试服务器，您需要获取适当的URL，登录ID，角色等。询问质量检查您是否应该更改或删除任何内容，因为有时组之间共享相同的测试环境。

此外，请确保您的登录名与用户将拥有的权限相对应。如果您具有管理员登录名，则可能会遇到与普通用户不同的响应。您可能还需要构造某些文件，以使用要测试的设置来配置服务器。

确切地了解如何创建文件，将文件上传到的目录，停止和重新启动的服务等等，可能需要进行大量的初步调查。

确切地，您要做的事情取决于您的产品，环境，公司和安全限制等。没有两家公司是一样的。有时候，设置测试系统很麻烦，而有时候却很轻松。

在一家公司中，要获得对测试系统的访问权限，我们必须跳过一系列安全性障碍。例如，从内部系统到Web服务的连接要求开发人员通过中间服务器。要连接到Web服务器测试实例，您必须使用SSL到中介服务器，然后再从中介连接到Web服务器。（这不是用户需要做的，只是内部工程师。）

第一次尝试这样做时，我要求开发人员帮助我进行设置。我仔细观察了他在计算机上执行的命令和步骤。后来我出于将来的知识目的对其进行了记录，而其他工程师使用我的文档来设置相同的访问权限。

测试本地版本

很多时候，开发人员在将系统推送到测试服务器之前先在系统的本地实例上工作。换句话说，他们将应用程序或Web服务器完全构建在自己的计算机上，并在那里运行测试代码，很久之后才将其推送到测试服务器。如果您这么早就加入该项目，那就太好了–您可能会对API的设计产生更大的影响，并可以根据需要影响更改。

要在本地构建代码，您可能需要安装特殊的实用程序或框架，熟悉各种命令行操作以构建代码，等等。如果您可以在自己的计算机上运行本地版本，那通常是值得的，因为它可以使您在发布之前很早就记录内容。

如果设置本地环境太复杂，您可以要求工程师在计算机上安装本地系统。有时，开发人员喜欢坐在您的计算机旁，接管安装和设置系统的任务。他们可以在命令终端上快速工作并对系统进行故障排除，或者快速执行安装命令，否则这些命令将很无聊。

很多时候，开发人员不太愿意设置您的系统，因此他们可能会为您提供有关安装此工具的快速说明。但是请不要让开发人员说“哦，您只需执行a，b和c”。然后，您回到办公桌，什么也没做，或者比他或她说的要复杂得多。可能需要坚持不懈才能首次设置并运行所有功能。

如果开发人员全神贯注于sprint任务并且积压了大量积压，则他或她可能没有时间来帮助您正确地进行设置。请耐心等待，并要求开发人员指出进行设置的好时机。

通过本地构建，建立功能系统比使用测试服务器更具挑战性。但是，如果您要编写良好的文档，则必须建立测试系统。优秀的开发人员了解并认识到这种需求，因此他们通常会（在一定程度上）帮助您建立测试环境以帮助您入门。

测试示例应用

根据产品的不同，您的代码交付物中可能还会有示例应用程序或SDK。您通常会在产品中包含示例应用程序或SDK（或使用各种编程语言的多个应用程序和SDK），以演示如何集成和调用API。如果您有集成了API的测试应用，则可能需要在自己的计算机上安装一些程序或框架，以使示例应用正常运行。

例如，您可能必须构建一个示例Java应用程序才能与系统进行交互-因此，您可能需要在计算机上安装Java开发工具包和Java IDE才能使其正常运行。如果应用程序使用PHP，则可能需要安装PHP。或者，如果是Android应用，则可能需要下载Android Studio并将其连接到虚拟（或实际）设备。

通常很少有关于如何运行示例应用程序的说明，因为开发人员认为用户已经在其计算机上设置了这些环境。（例如，如果用户还没有Java环境，那么选择Java应用就没有意义。）

该示例应用程序是最有用的文档之一。在设置示例应用程序并使之运行时，请寻找在代码注释中添加文档的机会。至少要使示例应用程序在您自己的计算机上运行，??并在文档中包含设置步骤。

测试硬件产品

如果您要记录硬件产品，则需要保护安装了正确版本的设备。大公司通常都有可用的原型设备。在某些公司中，可能会有信息亭，您可以在其中“刷新”（快速安装）设备上的特定内部版本号。或者，您也可以将设备的序列号发送给管理从云接收Beta版本更新的设备池的人员。

对于某些硬件产品，可能很难获得该产品的测试实例。我曾经在一个政府机构工作，记录一百万美元的存储阵列。唯一一次允许我看到存储阵列的方法是在工程师的陪同下登录特殊的数据服务器机房环境，他没有梦想让我真正接触阵列，更不用说换出存储磁盘了，运行命令在终端中，更换RAID或执行其他任务（我正在为其写指令）。

我很早就学会了将自己的职业引导到可以实际接触产品（通常是软件代码）并试用它的工作。在我目前的职位上，我有一个装有消防电视设备和原型的抽屉。通过Android Studio，我经常在这些物理设备之一上运行应用程序以测试其工作方式。

如果您要记录硬件，则需要访问该硬件以提供有关如何使用它的可靠文档。您需要了解如何在设备上运行应用以及如何与设备交互。希望该产品是您可以直接动手操作的产品。

如果遇到开发人员的抵制…

很多时候，开发人员并不期望技术作家会做任何事情，而不仅仅是抄录和转发工程师提供给他或她的信息。以这种心态，开发人员可能不会立即认为您需要或希望示例应用程序来测试调用或其他代码。您可能需要询问（甚至请愿）开发人员。

我发现，在大多数时候，如果技术作家可以自己测试代码，则开发人员会更尊重技术作家。工程师还非常感谢您在系统中运行时可能获得的任何反馈。技术写作人员和质量检查人员通常是开发人员代码的第一批用户。

如果开发人员或质量检查人员无法让您访问任何此类测试服务器或示例代码，请多加怀疑。开发和质量保证团队如何在没有示例系统的情况下创建和测试他们的代码，而示例系统无法实现这些代码？而且，如果有一个示例系统，为什么您也没有访问权限，以便您可以编写准确，详尽的文档以了解如何使用它？

有时，开发人员不想花很多时间在计算机上工作，因此您可能必须解释一下测试目的和目标。如果遇到摩擦，请坚持不懈。设置测试环境可能需要一到几天的时间。例如，花了我几天时间才能在我的Fire TV设备上成功构建一个应用程序框架。但是，一旦建立了测试系统，就可以更轻松地创建文档，因为您可以开始回答自己的问题。