README

eugene-erg/open-api 是一个 PHP 包，旨在以面向对象的方式简化 OpenAPI 配置的创建。此包允许开发者使用整洁且表达性强的 API 定义和管理 OpenAPI 模式、安全模式和其他组件。

特性

• 面向对象配置：使用 PHP 类和对象定义 OpenAPI 模式、安全模式以及组件。
• 丰富的模式支持：为 integer、number、string、boolean、object 和 untyped 数据类型创建复杂的模式。
• 安全模式：支持多种安全模式，包括 API Key、Bearer 和 OAuth2。
• 灵活的构建器：使用构建器类创建和管理模式和安全性方案。

优点

• 类型安全：利用 PHP 的强类型特性以获得更健壮且无错误的代码。
• 可读性：面向对象的方法使配置更易读且易于维护。
• 可扩展性：根据需要轻松扩展和自定义组件。

比较

安装

要安装该包，请运行以下命令

composer require eugene-erg/open-api

用法

创建模式

<?php

declare(strict_types = 1);

use EugeneErg\OpenApi\Builder;
use EugeneErg\OpenApi\Components;
use EugeneErg\OpenApi\Components\Parameters;
use EugeneErg\OpenApi\Components\RequestBodies;
use EugeneErg\OpenApi\Components\Responses;
use EugeneErg\OpenApi\Components\Schemas;
use EugeneErg\OpenApi\Info;
use EugeneErg\OpenApi\Openapi;
use EugeneErg\OpenApi\Paths;
use EugeneErg\OpenApi\Servers;

$error = new Schemas\Object\Schema(
    properties: new Schemas\Object\Properties(
        code: new Schemas\Object\Property(
            schema: new Schemas\Integer\Schema(
                format: Schemas\Integer\Format::Int32,
            ),
            required: true,
        ),
        message: new Schemas\Object\Property(
            schema: new Schemas\String\Schema(),
            required: true,
        ),
    ),
);

$categoryFilter = new Parameters\Query\SchemaParameter(
    schema: new Schemas\String\Schema(),
    description: 'Filter by category',
    required: false,
);

$priceRange = new Parameters\Query\SchemaParameter(
    schema: new Schemas\String\Schema(
        example: new Schemas\String\Value('10.00-100.00'),
        pattern: "^\\d+\\.\\d{2}-\\d+\\.\\d{2}$",
    ),
    description: 'Filter by price range',
    required: false,
);

$product = new Schemas\Object\Schema(
    properties: new Schemas\Object\Properties(
        id: new Schemas\Object\Property(
            schema: new Schemas\Integer\Schema(
                format: Schemas\Integer\Format::Int64,
            ),
            required: true,
        ),
        name: new Schemas\Object\Property(
            schema: new Schemas\String\Schema(),
            required: true,
        ),
        description: new Schemas\Object\Property(
            schema: new Schemas\String\Schema(),
        ),
        price: new Schemas\Object\Property(
            schema: new Schemas\Number\Schema(
                format: Schemas\Number\Format::Float,
            ),
            required: true,
        ),
        category: new Schemas\Object\Property(
            schema: new Schemas\String\Schema(),
        ),
    ),
);

$generalError = new Responses\Response(
    description: 'General error.',
    content: new RequestBodies\Contents(...[
        'application/json' => new RequestBodies\Content(
            schema: $error,
        ),
    ]),
);

$notFound = new Responses\Response(
    description: 'Entity not found.',
);

$category = new Schemas\Object\Schema(
    properties: new Schemas\Object\Properties(
        id:  new Schemas\Object\Property(
            schema: new Schemas\Integer\Schema(
                format: Schemas\Integer\Format::Int64,
            ),
            required: true,
        ),
        name: new Schemas\Object\Property(
            schema: new Schemas\String\Schema(),
            required: true,
        ),
    ),
);

$openapi =new Openapi(
    info: new Info(
        title: 'Advanced API',
        version: '1.0.0',
    ),
    paths: new Paths(...[
        '/products' => new Paths\Path(
            get: new Paths\Operation(
                responses: new Responses(
                    x200: new Responses\Response(
                        description: 'A list of products',
                        content: new RequestBodies\Contents(...[
                            'application/json' => new RequestBodies\Content(
                                schema: new Schemas\Array\Schema(
                                    items: $product,
                                ),
                            ),
                        ]),
                    ),
                    default: $generalError,
                ),
                summary: 'List all products',
                id: 'listProducts',
                parameters: new Parameters\Parameters(
                    queries: new Parameters\Query\Queries($categoryFilter, $priceRange),
                ),
            ),
        ),
    ]),
    components: new Components(
        schemas: new Schemas\Untyped\Schemas(
            Product: $product,
            Category: $category,
            Error: $error,
        ),
        responses: new Responses(
            NotFound: $notFound,
            GeneralError: $generalError,
        ),
        parameters: new Parameters(
            categoryFilter: new Parameters\Parameter(
                name: 'category',
                parameter: $categoryFilter,
            ),
            priceRange: new Parameters\Parameter(
                name: 'priceRange',
                parameter: $priceRange,
            ),
        ),
    ),
    servers: new Servers(
        new Servers\Server(
            url: 'https://api.advancedexample.com/v1',
            description: 'Main server',
        ),
    ),
);

/** @var array<string<fileName>, stdClass<OpenapiConfig>> $results */
$results = (new Builder($openapi))->prepareToSave('path/directory');

如果实体对象在组件中使用且需要，它将被转换为 $ref。