zrnik/zweist

使用 `zircote/swagger-php` 的 Slim Framework 4 开放的 API 路由

v0.3.7 2024-06-10 07:40 UTC

README

"我站在山峰上的 zweist" - Lenka Dusilová

这是什么?

这是一个为 Slim Framework 4 生成的路由工具,仅使用 zircote/swagger-php 属性(或可能为注解,未测试)来生成路由。

composer require zrnik/zweist

你的意思是什么?

1. 您使用 zircote/swagger-php 属性注释控制器方法

class HelloWorldController
{
    public function __construct(
        private readonly \Zrnik\Zweist\Content\JsonContentFacade $jsonContentFacade,
    ) {}

    /**
     * @param array<string, string> $arguments
     * @throws JsonException
     */
    #[
        Get(
            path: '/api/hello/{name:.*}',
            operationId: 'Say Hello',
            description: 'says hello by the request parameter',
        ),
        Response(
            response: 200,
            description: 'when ok',
            content: new JsonContent(ref: TestResponse::class)
        ),
        Middleware(ExampleMiddleware::class),
    ]
    public function sayHello(
        RequestInterface $request,
        ResponseInterface $response,
        array $arguments = []
    ): ResponseInterface
    {
        return $this->jsonContentFacade->updateResponse(
            $response,
            new TestResponse(
                sprintf(
                    'Hello, %s :)',
                    $arguments['name']
                )
            )
        );
    }
}

2. 将 ZweistConfiguration 添加到您的依赖注入(DI)中。

$zweistConfiguration = new ZweistConfiguration(
    
    // scan paths for openapi attributes (requests & schemas)
    [
        __DIR__ . '/../../Controllers',
        __DIR__ . '/../../Model',
    ], 
    
    // generated (and committed) files
    __DIR__ . '/openapi.json', 
    __DIR__ .'/router.json', 
);

3. 生成(并提交)openapi.jsonrouter.json

$zweistOpenApiGenerator = $container->get(ZweistOpenApiGenerator::class);
$zweistOpenApiGenerator->generate();

4. 让 ZweistRouteService 填充 \Slim\App 实例中的路由。

$zweistRouteService = $container->get(ZweistRouteService::class);
$zweistRouteService->applyRoutes($app);

您应该知道的其他事项

您需要创建一个包含 openapi 描述属性的类。(见 ./tests/ExampleApplication/ExampleApplicationInfo.php

您希望在开发时本地生成 openapi.jsonrouter.json,然后将它们与代码一起提交,因为您不希望在每次请求时都扫描所有文件以查找路由。

您应该在 CI 中检查是否已生成新文件。