README

使用 OpenAPI 规范是创建和共享 API 遵循的合同的好方法。此包将自动验证您的集成和功能测试中使用的请求和响应，无论在哪里使用 Laravel HTTP 测试方法（如 ->get('/uri') 等）。

幕后，此包将 Laravel 的 HTTP 辅助函数与 Laravel HTTP 辅助函数 连接到 PHP League 的 OpenAPI 验证器。

安装

您可以通过 composer 安装此包

composer require kirschbaum-development/laravel-openapi-validator

设置

在任意功能/集成测试（例如扩展框架的 Tests\TestCase 基类），添加 ValidatesOpenApiSpec 特性

use Kirschbaum\OpenApiValidator\ValidatesOpenApiSpec;

class HttpTest extends TestCase
{
    use ValidatesOpenApiSpec;
}

在许多情况下，默认设置应该处理配置。如果您需要自定义配置（特别是 openapi.yaml 或 openapi.json 文件的位置），使用以下命令发布配置

php artisan vendor:publish --provider="Kirschbaum\OpenApiValidator\OpenApiValidatorServiceProvider"

并在 config/openapi_validator.php 中配置 OpenAPI 规范的路径以适应您的需求。

用法

将特性应用到您的测试类后，每次您与 HTTP 测试方法（如 get、post、put、delete、postJson、call 等）交互时，验证器将验证请求和响应。

跳过验证

特别是在最初编写测试（如 TDD）时，关闭请求或响应验证直到测试接近完成可能很有帮助。您可以这样做：

public function testEndpointInProgress()
{
    $response = $this->withoutRequestValidation()->get('/'); // Skips request validation, still validates response
    // or
    $response = $this->withoutResponseValidation()->get('/'); // Validates the request, but skips response
    // or
    $response = $this->withoutValidation()->get('/'); // No validation
}

您可以根据上述示例链式调用这些方法，也可以单独调用它们

public function testEndpointInProgress()
{
    $this->withoutRequestValidation();
    $response = $this->get('/');
}

请注意，withoutRequestValidation()、withoutResponseValidation() 和 withoutValidation() 仅适用于 下一个 请求/响应，之后将重置。

基于响应代码跳过响应

默认情况下，我们假设任何 5xx 状态代码都不应被验证。您可以通过在测试类中设置受保护的 responseCodesToSkip 属性，或使用 skipResponseCode 方法添加响应代码（单个、数组或正则表达式模式）来更改此设置。

use Kirschbaum\OpenApiValidator\ValidatesOpenApiSpec;

class HttpTest extends TestCase
{
    use ValidatesOpenApiSpec;

    protected $responseCodesToSkip = [200]; // Will validate every response EXCEPT 200

    public function testNoRedirects()
    {
        $this->skipResponseCode(300); // Will skip 200 and 300
        $this->skipResponseCode(301, 302); // Will skip 200, 300, 301, 302
        $this->skipResponseCode('3[1-2]1'); // Will skip 200, 300, 301, 302, 311, and 321
        // ...
    }
}

身份验证/授权

在大多数测试中，您可能使用 Laravel 的辅助函数，如 actingAs($user) 来处理身份验证。此包默认假设您正在使用 bearer 令牌作为授权头，并且此信息已指定在您的 OpenAPI 规范中。验证器会期望授权作为请求的一部分，即使 Laravel 不会发送它们。如果您使用的是除 bearer 令牌之外的安全机制，您应该覆盖 getAuthenticatedRequest 方法并添加适当的头。请注意，它们不需要有效（除非您的代码会检查它们），只需存在以满足验证器即可。

贡献

有关详细信息，请参阅 CONTRIBUTING。

安全

如果您发现任何安全相关的问题，请通过电子邮件 zack@kirschbaumdevelopment.com 或 nathan@kirschbaumdevelopment.com 报告，而不是使用问题跟踪器。

致谢

• Zack Teska

赞助

本包的开发由Kirschbaum Development Group资助，这是一家以解决问题、团队建设和社区为中心的驱动型开发公司。了解更多 关于我们 或 加入我们！

许可证

MIT许可证（MIT）。请参阅许可证文件以获取更多信息。