README

用于创建“约定优先”API应用程序的PHP库。

支持的格式

OpenAPI 2.0 (FKA Swagger)

有限

RAML 1.0^*

^* RAML 是一个比 OpenAPI 更丰富且更详尽的标准，支持全部功能的完整支持需要一些时间。欢迎提供帮助。

目标是提供全面的支持和互操作性。

典型用法

验证请求和响应

省略命名空间以简化

$validator = new MessageValidator(
  (new Repository('some/path'))->get('some-service/v1.0.1/swagger.yml')
);
/** @var ServerRequestInterface $request */
$result = $validator->validateRequest($request, $path);

/** @var ResponseInterface $response */
$result = $validator->validateResponse($body, $request, $response, $path);

如果您想尝试使用 RAML 支持

$validator = new MessageValidator(
    (new Repository())
        ->setFactory(new DescriptionFactory(DescriptionFactory::BUILDER_RAML))
        ->get('tests/definitions/raml/mobile-order-api/api.raml')
);

(反-)脱水

// $input is deserialized and validated using $inputSchema

$builder   = new ProcessorBuilder(new ClassNameResolver(['Some\Namespace']));
$processor = $builder->build($schema);
$hydrated  = $processor->hydrate($input, $inputSchema);

// Perform business logic, creating $appOutput

$output = $processor->dehydrate($appOutput, $outputSchema);

// Validate output using $outputSchema

NULLs、未定义和默认值

处理器将假设脱水输入已预先验证。这意味着当输入对象包含具有 NULL 值的属性时，它将保留原样，如果输入无效（否则将通过 NullProcessor 进行“脱水”），则可能将其转换为非 NULL 的值。

因此，隐含的流程是：输入 > 反序列化 > 验证 > 脱水 > 业务逻辑 > 脱水 [> 验证] > 序列化 > 输出。

遵循此流程时，行为应该是直观的。有关实现的详细说明，请参阅此处。

DateTime

可以通过配置 DateTimeProcessor 工厂的自定义 DateTimeSerializer 实例（通过构建器）来调整输入和输出的预期格式。

$builder = new ProcessorBuilder($classNameResolver, new DateTimeSerializer(\DateTime::RFC850));

默认输出格式为 'Y-m-d\TH:i:s.uP'（带有微秒的 RFC3339）。当传递时，将使用第一个构造函数参数代替。输入解析尝试如下：

构造函数参数
RFC3339，精度递减
1. RFC3339，带有微秒
2. RFC3339，带有毫秒
3. RFC3339
ISO8601

注意：不以 Y-m-d 开头的格式不适用于 Schema::FORMAT_DATE 或 AnyProcessor。

自定义处理器

通过将自定义实例注入到构建器中，可以调整类名解析和 DateTime 处理，但几乎可以自定义脱水和脱水过程中的所有部分。您可以通过将它们的工厂注入到“处理器工厂队列”中来注入自定义处理器。所有处理器及其工厂都对外开放扩展。用例包括

从数据存储加载对象
维护结构中重复出现的对象身份
自定义类型对象活化（例如使用构造函数、设置器）
根据类型创建自定义对象
在对象创建时发出领域事件
强制转换标量值（例如将'false'解释为FALSE）
基本上你可以想到的所有其他事情

一些示例可以在这里找到。

性能预期

在我的旧Xeon W3570上，1000个真实对象（嵌套对象、数组）的活化和脱水大约需要100ms；平均每个根对象略小于1ms。

集成

如果你想在Symfony中结合使用OpenAPI，你应该查看SwaggerBundle。

还有PSR-7/PSR-15 Middleware，其行为几乎相同，但更可重用。

限制

RAML支持非常有限
不与表单数据一起工作
需要路由器来确定匹配的路径
如果请求有正文，它将必须使用对象而不是关联数组进行反序列化
需要未序列化的响应体
响应验证不验证头和内容类型（尚未实现）

贡献

欢迎提交拉取请求，但代码必须符合PSR2规范，遵循有关参数和返回类型声明的惯例，并且覆盖率不能下降。

许可

KleijnWeb\PhpApi\Descriptions是在LGPL，版本3.0的条款下提供的。

kleijnweb / php-api-descriptions

维护者

详细信息