README

atoum/apiblueprint-extension

候选者:

1. atoum是一个PHP测试框架，
2. API Blueprint是一种高级HTTP API描述语言。

问题：API Blueprint只是一个文本文件。对人类来说容易阅读，但是机器无法对其做任何事情。

解决方案：将API Blueprint文件编译成可执行的测试。它像使用atoum API编写的任何测试一样工作，并在atoum生态系统中工作。以下是工作流程概述

更详细地说，以下是具体发生的事情

1. 搜索器遍历.apib文件，
2. 对于每个文件，将其解析为中间表示，
3. 中间表示被编译成目标“atoum测试”，
4. 新测试被推送到atoum的测试队列中，
5. atoum按常规执行一切。

额外功能：提供了一个非常简单的脚本来将多个API Blueprint文件作为独立的HTML单页文件进行渲染。

安装和配置

使用Composer，要将此扩展包含到依赖项中，您需要添加atoum/apiblueprint-extension

$ composer require atoum/apiblueprint-extension '~0.2'

要启用扩展，必须编辑.atoum.php配置文件以添加

$extension = new atoum\apiblueprint\extension($script);
$extension->addToRunner($runner);

配置搜索器

假设.apib文件位于./apiblueprints目录中，以下代码将此目录添加到API Blueprint搜索器中，编译一切为测试，并将它们排队

$extension->getAPIBFinder()->append(new FilesystemIterator('./apiblueprints'));
$extension->compileAndEnqueue();

配置JSON模式的位置（当在.apib文件外部定义时）

API Blueprint使用JSON Schema在消息旨在是有效JSON消息时，用于验证HTTP请求和响应。

出于几个原因，我们建议在.apib文件外部定义JSON模式

• 它们可以独立于.apib文件进行版本控制，
• 它们可以在您的应用程序内部使用以验证传入的HTTP请求或传出的HTTP响应，
• 它们可以被其他工具使用。

为此，必须经过以下两个步骤

1. 使用扩展的配置帮助挂载JSON模式目录，
2. 在Schema部分中使用{"$ref": "json-schema://<mount>/schema.json"}。

示例

1. 在配置扩展的.atoum.php文件中

   $extension->getConfiguration()->mountJsonSchemaDirectory('test', '/path/to/schemas/');

2. 在API Blueprint文件中

   + Response 200
   
     + Schema
   
       {"$ref": "json-schema://test/api-foo/my-schema.json"}

   其中test是“挂载点名称”，而/api-foo/my-schema.json是位于/path/to/schemas/api-foo/my-schema.json的有效JSON模式文件。

测试

在运行测试套件之前，必须安装开发依赖项

$ composer install

然后，要运行所有测试套件

$ composer test

符合API Blueprint规范

此atoum扩展实现了API Blueprint规范。

欢迎任何帮助!

许可

请参阅LICENSE文件。本项目使用与atoum相同的许可证。