README

PHP 中间件，用于解析并将 swagger 信息附加到请求对象中。

安装

建议您使用 Composer 安装 swagger-router-middleware。

$ composer require avalanche-development/swagger-router-middleware

swagger-router-middleware 需要 PHP 5.6 或更高版本。

使用方法

此中间件以 swagger（数组形式）实例化，然后作为中间件调用时，将遍历 swagger 文档并解析内容。具体来说，它将提取路径和操作，解析参数和安全定义，并根据 swagger 定义解析参数。

$router = new AvalancheDevelopment\SwaggerRouterMiddleware\Router([..swagger..]);
$result = $router($request, $response, $next); // middleware signature

建议将其作为堆栈中的顶级项之一，因为解析出的 swagger 信息可以用于更深入地验证请求/响应。

接口

一旦所有内容成功通过，$request 对象将具有以下属性。

'swagger' => [
    'apiPath' => '/comments/{comment_id}', // matched string path
    'path' => [ ... ], // full path definition
    'operation' => [ ... ], // specific operation definition
    'params' => [ ... ], // resolved list of parameters for this operation
    'security' => [ ... ], // resolved list of securities
    'schemes' => [ ... ], // resolved list of schemes
    'produces' => [ ... ], // resolved list of producible content types
    'consumes' => [ ... ], // resolved list of consumable content types
    'responses' => [ ... ], // resolved list of responses
]

需要注意的是，列表中的每个参数都将包含一个 'value' 键，如果该参数已传递到请求中（或具有默认值），则将填充该键。

文档路由

如果检测到标准的 '文档路由'（/api-docs 路径），则立即跳过堆栈的其余部分，并以 json 格式返回 swagger 规范。如果 json_encode 抛出错误，则抛出标准的 \Exception。

无效请求

这里进行了一些路由操作。如果请求路由在 swagger 中找不到，或者不支持该方法，将抛出适当的 peel 异常。此外，如果参数解析出现错误，看起来像请求问题，将抛出 peel BadRequest。错误处理器可以监听这些 HttpErrorInterface 异常并作出相应的响应。

参数解析

中间件将尽可能解析请求的参数而不过多进行验证。它循环遍历 swagger 定义，寻找适用于路由的参数，并从头部/查询/路径等中提取它们。

再次强调，此中间件不会根据规范检查参数的存在、有效性或类型。它仅尝试提取并期望堆栈中的其他部分进行验证。

开发

此库仍在开发中，可能会遇到一些错误。如果您注意到任何问题，请随时提交问题或拉取请求。

测试

要执行测试套件，您需要 phpunit（以及安装带有开发依赖项的包）。

$ phpunit

许可

swagger-router-middleware 在 MIT 许可下授权。有关更多信息，请参阅 许可文件。