README

简介

用于 swagger-php 的可重用注解。

安装

您可以使用 composer 或直接 下载发布版。

Composer

首选方法是通过 composer。如果您尚未安装 composer，请按照 安装说明 进行操作。

安装此库

composer require radebatz/openapi-extras

注册库

使用包含的注解/属性需要注册自定义处理器。在注解的情况下，还需要注册自定义别名/命名空间。

注册库以使用属性

<?php

use OpenApi\Generator;
use OpenApi\Processors\BuildPaths;
use Radebatz\OpenApi\Extras\Processors\MergeControllerDefaults;

$generator = new Generator();

// ...

$generator->addProcessor(new MergeControllerDefaults(), BuildPaths::class);

// ...

注册库以使用注解

<?php

use OpenApi\Generator;
use OpenApi\Processors\BuildPaths;
use Radebatz\OpenApi\Extras\Processors\MergeControllerDefaults;

$generator = new Generator();

// ...

$namespace = 'Radebatz\\OpenApi\\Extras\\Annotations';
$generator
    ->addNamespace($namespace . '\\')
    ->addAlias('oax', $namespace),
    ->addProcessor(new MergeControllerDefaults(), BuildPaths::class);

// ...

基本用法

控制器

控制器注解可用于类级别，为该控制器类的所有操作添加可选的前缀。

它还可以用于为所有端点添加默认响应。

示例：为 MyController 类中的所有操作添加 /foo 前缀和一个 403 响应。

<?php declare(strict_types=1);

use OpenApi\Attributes as OAT;
use Radebatz\OpenApi\Extras\Attributes as OAX;

#[OAX\Controller(prefix: '/foo')]
#[OAT\Response(response: 403, description: 'Not allowed')]
class PrefixedController
{
    #[OAT\Get(path: '/prefixed', operationId: 'prefixed')]
    #[OAT\Response(response: 200, description: 'All good')]
    public function prefixed(): mixed
    {
        return 'prefixed';
    }
}

中间件

当前 Middleware 注解未使用，但将在 openappi-router 项目的未来版本中使用。

许可证

openapi-extras 项目在 MIT 许可证 下发布。