README

一个 PHP 库，可以将 OpenAPI schema 或参数对象转换为 JSON Schema。

这是由 nodejs 包 @mikunn 的一个端口。

它目前可以将 OpenAPI 3.0 转换为 JSON Schema Draft 4。

为什么？

OpenAPI 是一种用于描述 RESTful API 的规范。OpenAPI 3.0 允许我们详细地描述请求和响应负载的结构。理论上，这意味着我们应该能够自动验证请求和响应负载。然而，在撰写本文时，还没有太多验证器。

好消息是，有许多 JSON Schema 验证器，例如 justinrainbow/json-schema。坏消息是，OpenAPI 3.0 并不完全与 JSON Schema 兼容。OpenAPI 3.0 的 Schema 对象是 JSON Schema 规范 Wright Draft 00 的扩展子集，有一些差异。

本项目旨在通过在这些格式之间进行转换来填补这一空白。

特性

• 将 OpenAPI 3.0 Schema 对象转换为 JSON Schema Draft 4
• 将 OpenAPI 3.0 Parameter 对象转换为 JSON Schema Draft 4
• 如果 nullable 为 true，则删除 nullable 并在 type 数组中添加 "null"
• 支持嵌套 allOf 等的深层结构
• 除非指定，否则删除 OpenAPI 特定属性，如 discriminator、deprecated 等。
• 可选地支持 Schema 对象中的 patternProperties 与 x-patternProperties

注意：不解析 $ref。在使用此包之前，请使用解析器。

安装

此库可以通过 Composer 安装。

composer require benmorel/openapi-schema-to-json-schema

要求

此库需要

• PHP 7.2 或更高版本
• json 扩展

没有对第三方库的依赖。

项目状态及发布流程

当前版本编号为 0.x.y。当引入非破坏性更改（添加新方法、优化现有代码等）时，y 增加。

当引入破坏性更改时，始终启动新的 0.x 版本周期。

因此，可以将项目锁定到给定的发布周期，例如 0.1.*。

如果您需要升级到较新的发布周期，请查看 发布历史，以了解每个进一步的 0.x.0 版本引入的更改列表。

转换 OpenAPI schema

以下是一个小示例来获取概念

use BenMorel\OpenApiSchemaToJsonSchema\Convert;

$schema = json_decode(<<<'JSON'
    {
        "type": "string",
        "format": "date-time",
        "nullable": true
    }
JSON
);

$convertedSchema = Convert::openapiSchemaToJsonSchema($schema);

echo json_encode($convertedSchema, JSON_PRETTY_PRINT);

示例输出

{
    "type": [
        "string",
        "null"
    ],
    "format": "date-time",
    "$schema": "http:\/\/json-schema.org\/draft-04\/schema#"
}

转换 OpenAPI 参数

OpenAPI 参数可以被转换

use BenMorel\OpenApiSchemaToJsonSchema\Convert;

$param = json_decode(<<<'JSON'
    {
        "name": "parameter name",
        "in": "query",
        "schema": {
            "type": "string",
            "format": "date"
        }
    }
JSON
);

$convertedSchema = Convert::openapiParameterToJsonSchema($param);

echo json_encode($convertedSchema, JSON_PRETTY_PRINT);

结果如下所示

{
    "type": "string",
    "format": "date",
    "$schema": "http:\/\/json-schema.org\/draft-04\/schema#"
}

当参数有多个 schema（每个 MIME 类型一个）时，返回一个映射

{
    "name": "parameter name",
    "in": "query",
    "content": {
        "application/javascript": {
            "schema": {
                "type": "string"
            }
        },
        "text/css": {
            "schema": {
                "type": "string"
            }
        }
    }
}

将被转换为

{
    "application\/javascript": {
        "type": "string",
        "$schema": "http:\/\/json-schema.org\/draft-04\/schema#"
    },
    "text\/css": {
        "type": "string",
        "$schema": "http:\/\/json-schema.org\/draft-04\/schema#"
    }
}

选项

两个函数 Convert::openapiSchemaToJsonSchema() 和 Convert::openapiParameterToJsonSchema() 都接受一个关联数组 $options 作为第二个参数，以下是一些键

cloneSchema (布尔型)

如果设置为 false，则在原地对提供的模式进行转换。如果设置为 true，则通过将其转换为 JSON 并返回来克隆模式。克隆的开销通常可以忽略不计。默认为 true。

dateToDateTime (布尔型)

默认为 false，保留 date 格式不变。如果设置为 true，则将 format: 'date' 设置为 format: 'date-time'。

例如

{
  "type": "string",
  "format": "date"
}

被转换为

{
    "type": "string",
    "format": "date-time",
    "$schema": "http:\/\/json-schema.org\/draft-04\/schema#"
}

keepNotSupported (数组)

默认情况下，以下字段将从结果模式中删除： nullable、discriminator、readOnly、writeOnly、xml、externalDocs、example 和 deprecated，因为它们不受 JSON Schema Draft 4 的支持。提供您想要保留的字段数组（作为字符串），它们不会被删除。

removeReadOnly (布尔型)

如果设置为 true，则将删除设置为 readOnly 的属性。如果该属性设置为 required，则它也将从 required 数组中删除。即使 readOnly 被设置为与 keepNotSupported 一起保留，该属性也将被删除。

removeWriteOnly (布尔型)

与 removeReadOnly 类似，但对于 writeOnly 属性。

supportPatternProperties (布尔型)

如果设置为 true 并且存在 x-patternProperties 属性，则将 x-patternProperties 更改为 patternProperties 并调用 patternPropertiesHandler。如果没有定义 patternPropertiesHandler，则调用默认处理器。有关更多信息，请参阅 patternPropertiesHandler。

patternPropertiesHandler (函数)

提供一个函数来处理模式属性，并设置 supportPatternProperties 以生效。该函数接受在根级别定义 x-patternProperties 的模式。此时，x-patternProperties 被更改为 patternProperties。它必须返回修改后的模式。

如果没有提供处理器，则使用默认处理器。如果 additionalProperties 被设置为对象，并且与 patternProperties 内部的模式对象具有深度相等，则默认处理器将其设置为 false。这是因为我们可能在 OpenAPI 规范文件中定义 additionalProperties，但希望针对模式进行验证。如果允许具有相同结构的 additionalProperties，则模式将变得无用。创建自己的处理器以覆盖此功能。

有关如何工作的示例，请参阅 tests/PatternPropertiesTest.php。