README

一个用于创建 OpenApi 规范的 PHP 库

支持的 OpenApi 版本

版本 3.1.0.

支持的输出格式

目前库支持将 OpenApi 规范转换为数组，可以轻松地在端点中编码为 JSON 或序列化以供缓存和后续作为 JSON 交付。

根据规范支持 YAML，但目前尚不支持直接支持。

示例用法

导出模式为 JSON

// Class: MyDomainOpenApiGenerator.php

public class MyDomainOpenApiGenerator extends \Finderly\OpenapiPhpLib\OpenApiGenerator
{
    public function __construct(/* inject your dependencies here */) {}

    /**
     * your generation logic goes here, sample below
     * @return array
     */
    public function generateSpecification(): array
    {
        $mySchemas = $myPaths = [/* your domain logic here to populate these vars */];

        $openApi = new \Finderly\OpenapiPhpLib\Model\OpenApi(
            \Finderly\OpenapiPhpLib\Model\OpenApi::OPENAPI_VERSION,
            ['title' => 'My Spec\'s title', 'version' => 'My spec\'s version']
        );

        // add global schemas
        foreach ($mySchemas as $mySchema) {
            // $mySchema is your domain logic
            $openApi->getComponents()->addSchema(
                $mySchema->translateToOpenapiPhpLibSchemaName(),
                $mySchema->translateToOpenapiPhpLibSchema()
            );
        }

        foreach ($myPaths as $myPath) {
            // $myPath is your domain logic
            $pathItem = new \Finderly\OpenapiPhpLib\Model\Path\PathItem();
            $pathItem->setParameters(
                $myPath->translateToOpenapiPhpLibParameters()
            );

            foreach ($myPath->getSupportedHttpOperations() as $method) {
                $operation = $method->translateToOpenapiPhpLibOperation();
                $pathItem->setOperation(strtolower($method->getHttpMethod()), $operation);
            }

            $openApi->addPathItem($myPath->getHttpPath(), $pathItem);
        }

        return $openApi->toArray();
    }
}

// File: generation_command.php

$openApiGenerator = new MyDomainOpenApiGenerator();

$exporter = new \Finderly\OpenapiPhpLib\Exporter\OpenApiJsonExporter(
    $openApiGenerator
);

$exporter->exportFile('/path/to/file.json');

贡献和完整性

支持的 OpenApi 对象

以下对象目前得到支持

• body-object
• components-object
• item-object
• license-object
• openapi-object
• operation-object
• parameter-object
• paths-object
• reference-object
• response-object
• schema-object
• server-object
• type-object
• variable-object

如果您在此列表中没有找到您要找的内容，请与我们联系或贡献它！

贡献

可以通过使用以下变量类型相对容易地添加新对象。

变量类型

基本类型

• 字符串
• 数组
• 布尔型
• 整数

在渲染规范时，这些变量类型被视为它们的标准变量类型。

对象类型

• 对象
• 对象数组
• 对象[k,v]

在渲染规范时，这些变量类型是递归的。一个 object 是递归的。一个 object[] 被视为对象数组。在 "Paths" 和任何 "Map[string, OpenApi Object Type]" 被处理为 object[k,v]。