README

使用现有的 Laravel 测试进行 OpenAPI 文档验证。

TL;DR

composer require --dev webparking/laravel-openapi-validator

<?php

namespace Tests;

use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
use Webparking\OpenAPIValidator\ValidatesHttpMessagesAgainstDocs;

abstract class TestCase extends BaseTestCase
{
    use CreatesApplication;
    use ValidatesHttpMessagesAgainstDocs;
}

问题所在

在创建和维护 HTTP REST API 时，您希望确保它运行良好且文档齐全。我们认为能够自动检查这两者至关重要。

我们之前尝试过的方法

我们创建了一个系统，可以从 API 文档生成测试。对于大多数测试来说，它都奏效。但是，在测试中包含边缘情况几乎是不可能的。例如：有一个端点在收到特定输入时返回 500 状态码。您修复了错误并希望添加一个测试来确保它确实得到修复并保持修复状态。为此，您必须在文档中包含错误情况。您不希望生活在一个类似黑客的世界中。
我们创建了一个系统，可以根据应用程序的代码生成文档。首先，在文档中解释细微差别和抽象概念将非常困难，因为它们在应用程序中没有正式的位置。我们必须将文档分为两部分：从代码生成的技术规范和某种类型的维基百科中的补充说明。是的，随着时间的推移，它们会变得不一致。其次，为了实现这一点，您的应用程序代码需要非常非常结构化。我们非常重视通过一致性来维护质量，但在实践中，总是会有一个或两个边缘情况，其中实际偏离是更好的。

我们的解决方案

我们通过覆盖 Laravel HTTP 测试和 ThePHPLeague 的 OpenAPI PSR7 验证器来结合 MakesHttpRequests#call。在执行请求之前，我们将其与 OpenAPI 文档进行验证。在返回响应之前，我们也进行验证。对于发现的问题抛出异常。

此解决方案使我们能够最大限度地利用 OpenAPI 和 HTTP 测试；无需妥协。

使用方法

只需在测试类中使用 ValidatesHttpMessagesAgainstDocs。我们通常在项目级别 TestCase 中这样做。

文档的默认索引文件为 docs/index.yaml，但您可以设置 yamlPath 属性来覆盖它。

您可能希望排除某些 URI 的验证。为此，设置 ignoredUris 属性。

webparking / laravel-openapi-validator

维护者

详细信息