README

PSR-7 和 PSR-15 OpenAPI 验证中间件

该中间件解析 OpenAPI 定义文档（openapi.json 或 openapi.yaml）并进行验证

• 请求参数（路径、查询）
• 请求体
• 响应体

该中间件可以与任何使用 PSR-7 和 PSR-15 风格中间件的框架一起使用。

所有测试都使用 Slim 框架 完成。测试使用一个有效的 openapi.json 文件，该文件根据 Swagger/OpenAPI CLI 进行验证。

安装

建议您使用 Composer 进行安装。

composer require hkarlstrom/openapi-validation-middleware

使用 Swagger/OpenAPI CLI 验证 openapi.json/openapi.yaml 文件，因为中间件假设它是有效的。

使用方法

使用 Slim 框架的基本使用方法。

$config = [
    'settings' => [
        'determineRouteBeforeAppMiddleware' => true,
    ],
];
$app = new \Slim\App($config);
$app->add(new HKarlstrom\Middleware\OpenApiValidation('/path/to/openapi.json'));

使用 Zend Expressive 的基本使用方法。

$app = $container->get(\Zend\Expressive\Application::class);
$app->pipe(new HKarlstrom\Middleware\OpenApiValidation('/path/to/openapi.json'));

选项

选项数组在构建中间件时传递。

$app = new Slim\App;
$app->add(new HKarlstrom\Middleware\OpenApiValidation('/path/to/openapi.json'),[
    'additionalParameters' => true,
    'stripResponse' => true
]);

beforeHandler

如果已定义，则在调用下一个中间件之前，如果请求验证失败，将调用此函数。您可以使用它来在将请求传递给下一个中间件之前修改请求。如果返回除 \Psr\Http\Message\ServerRequestInterface 之外的任何内容，则将引发异常。数组 $errors 包含所有验证错误。

$options = [
    'beforeHandler' => function (\Psr\Http\Message\ServerRequestInterface $request, array $errors) : \Psr\Http\Message\ServerRequestInterface {
        // Alter request
        return $request
    }
];

errorHandler

如果已定义，则调用该函数而不是默认的错误处理程序。如果返回除 Psr\Http\Message\ResponseInterface 之外的任何内容，它将回退到默认错误处理程序。

$options = [
    'errorHandler' => function (int $code, string $message, array $errors) : \Psr\Http\Message\ResponseInterface {
        // Alter request
        return $request
    }
];

validateSecurity

如果已定义，则回调可以返回 Psr\Http\Message\ResponseInterface，如果操作不允许。$type 可以是 none、http 或 apiKey。

$options = [
    'validateSecurity' => function (ServerRequestInterface $request, string $type, string $token = '', ?array $scopes) : ?\Psr\Http\Message\ResponseInterface {
        // if user is authorized
        return null;

        // create and return error response
        $response = new Response( ... );
        return $response;
    }
];

格式

有两种方式来验证在 OAS 规范中未定义的格式。您可以实现自定义格式验证器并将其添加到中间件中，或者使用内置对 Respect Validation 库的支持。

自定义验证器

class MyOwnFormat implements Opis\JsonSchema\Format {
    public function validate($data) : bool
    {
        // Validate data
        // $isValid = ...
        return $isValid;
    }
}

$mw = new HKarlstrom\Middleware\OpenApiValidation('/path/to/openapi.json');
$mw->addFormat('string','my-own-format',new MyOwnFormat());
$app->add($mw);

Respect Validation

您可以通过在 openapi.json/openapi.yaml 文件中设置 format 属性来使用 所有验证器。

"schema":{
    "type" : "string",
    "format": "country-code"
}

值 country-code 将解析为 v::countryCode() 验证器。

您还可以向格式属性中定义的验证器传递参数

"schema": {
    "type": "string",
    "format":"ends-with('@gmail.com')"
}

或

"schema": {
    "type": "integer",
    "format":"between(10, 20)"
}

许可协议

OpenAPI 验证中间件采用 MIT 许可协议。有关更多信息，请参阅 许可文件。