README

使用 Codeception 验证您的 API 与 Swagger 2.0 的兼容性

如何安装

composer require --dev mlambley/swagception

什么是 Swagger？

Swagger 2.0（也称为 Open API 2.0）定义了您的 API 结构，包括端点以及输入和输出数据的结构。有关更多信息，请访问他们的网站。

什么是 Swagception？

如果您已有现有的 Swagger 2.0 规范，可以使用该规范通过此工具验证您的 API。此工具旨在与 Codeception 一起使用。具体来说，它将自动生成您的 API 的验收测试。它不会验证规范本身。它只会验证您的 API 是否与现有的规范匹配。

为什么选择 Swagception？

我找不到任何使用 Swagger 并专为 Codeception 设计的 API 验证器。此外，这个库旨在完全考虑 Swagger 2.0 规范的所有功能。

验收测试生成

您的 Swagger 规范中的路径可能看起来像这样 /api/entity/{entityID}/other/{otherID} 那么我们如何使用真实的实体 ID 生成实际的 URL，从而产生一个真实响应呢？默认情况下，此库将使用 enum 和 x-example 字段来完成此操作。然而，能够指定您自己的 ID 会更有用。您可以创建每个实体的处理器。使用注解将它们链接到一个或多个路径。然后，您只需告诉系统它们的位置即可。

namespace My\API\PathHandlers

/**
 * @path /api/entity/{entityID}/other/
 * @path /api/entity/{entityID}/other/{otherID}
 */
class MyPathHandler implements \Swagception\PathHandler\HandlesPath
{
    public function convertPath($path)
    {
        //Replace {entityID} with a real id
        if (strpos($path, '{entityID}') !== false) {
            $path = str_replace('{entityID}', $this->getEntityID(), $path);
        }

        //Replace {otherID} with a real id
        if (strpos($path, '{otherID}') !== false) {
            $path = str_replace('{otherID}', $this->getOtherID(), $path);
        }

        return $path;
    }

    protected function getEntityID()
    {
        //$ids = 100 valid entity ids. Pulled from either the database or the api.
        return $ids[mt_rand(0, 99)];
    }

    protected function getOtherID()
    {
        //$ids = 100 valid other ids. Pulled from either the database or the api.
        return $ids[mt_rand(0, 99)];
    }
}

Swagception 扩展

现在您已有了一些实际数据可供使用，是时候为 Swagception 配置您的 Codeception 环境。您只需设置一个扩展。有关 Codeception 扩展的更多信息，请在此处查看。请在您的 codeception.yml 或 suite.yml 文件中放置以下内容

extensions:
  enabled:
    - \Swagception\Extension\Swagception

Cest 结构

在启用 Swagception 的全部功能后，是时候在您的 Codeception cest 中将所有这些内容链接在一起。推荐的方法是将路径（端点）输入到 cest 数据提供者中。您的终端将为每个路径输出一行。

class MyCest
{
    use \Swagception\ContainerTrait;

    public function __construct()
    {
        //Configure the swagger schema object.
        $this->swaggerContainer = new \Swagception\Container\Container();

        $this->swaggerContainer->getSchema()
            //Path to your existing Swagger specification
            ->withSchemaURI('/path/to/swagger.json')
        ;

        //Configure the path handler loader.
        $this->swaggerContainer->getPathHandlerLoader()
            //Set this if you are using your own path handlers, and not relying upon enum and x-example.
            ->withNamespace('My\\API\\PathHandlers')

            //Set this if your path handler classes have not been loaded into the system yet.
            ->withFilePath('/path/to/pathhandlers/')
        ;
    }

    /**
     * @dataProvider _pathProvider
     */
    public function path(MyTester $I, \Codeception\Scenario $S, \Codeception\Example $data)
    {
        $path = $data[0];
        $this->swaggerContainer->getSchema()->testPath($path);
    }

    protected function _pathProvider()
    {
        //Will return an array of arrays.
        return array_map(function($val) {
            return [$val];
        }, $this->swaggerContainer->getSchema()->getPaths());
    }
}

或者，您可以在单个函数中循环它们。

public function paths(MyTester $I, \Codeception\Scenario $S)
{
    $schema = $this->swaggerContainer->getSchema(); 
    foreach ($schema->getPaths() as $path) {
        $schema->testPath($path);
    }
}

或者，如果您已经有了 json 和 schema 对象，可以直接调用验证方法。

(new \Swagception\Validator\Validator())
    ->validate($schema, $json);

有问题？

记录github 问题。您的帮助将被感激。

mlambley / swagception

维护者

详细信息