README

rest-spec

一个用于创建自我验证的API规范和端到端测试的简单库，使用PHP编写。

我目前不推荐在生产环境中使用它，但如果您愿意，我会很高兴。

安装

您可以通过Composer安装rest-spec。

将包添加到您的项目中的composer.json文件

{
    "require-dev": {
        "talkrz/rest-spec": "dev-master"
    }
}

使用Composer安装

composer install

使用方法

基本示例：描述GitHub API

在项目的根目录下创建rest-spec目录。

在目录内创建github.php文件（您可以选择任何文件名），并在其中编写API规范

<?php
# rest-spec/github.php

api('https://api.github.com', function() {
    url('/repos/{userName}/{repoName}', 'Fetch user repository data', function() {
        useCase('Fetch octocat\'s hello-world repository', function() {
            givenRequest()
                ->method('GET')
                ->headers([
                    'User-agent' => 'rest-spec'
                ]);

            expectResponse()
                ->toHaveStatusCode(200)
                ->toHaveHeaders([
                    'Content-Type' => 'application/json; charset=utf-8',
                    'Cache-Control' => 'public, max-age=60, s-maxage=60',
                    'Access-Control-Allow-Origin' => '*',
                ])
                ->toBeJson()
                ;
        })->withExampleParameters([
            'userName' => 'octocat',
            'repoName' => 'hello-world',
        ]);
    });
});

运行rest-spec

php vendor/bin/rest-spec

就是这样！

运行此命令后，您应该看到之前定义的规范与真实API验证的结果

始终是最新的规范

此库有两个主要用途。第一个是提供始终是最新的API规范。

让我们将上一个示例中的响应规范更改为一个无效的规范

<?php
# rest-spec/github.php

api('https://api.github.com', function() {
    url('/repos/{userName}/{repoName}', 'Fetch user repository data', function() {
        useCase('Fetch octocat\'s hello-world repository', function() {

        // ...
                ->toHaveHeaders([
                    'Content-Type' => 'application/json', // wrong header!
                    'Cache-Control' => 'public, max-age=60, s-maxage=60',
                    'Access-Control-Allow-Origin' => '*',
                ]);
        // ...
    });
});

运行rest-spec后，我们发现，实际的响应包含与规范中不同的头，因此我们知道需要更新它

另一个用途是测试您的应用程序。由于rest-spec会对实际应用程序进行调用，因此它可以检测到问题。当然，您应该记住，这种端到端测试非常有限。它只测试非常狭窄的功能集和应用程序中代码执行的路径。编写良好的单元测试集合对于检测错误来说更为重要。