zrnik/zweist

OpenAPI routing for Slim Framework 4 with `zircote/swagger-php`

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

Requires

• php: >=8.1.0
• eventsauce/object-hydrator: ^1.4
• nette/utils: ^3||^4
• nyholm/psr7: ^1.8
• slim/slim: ^4
• zircote/swagger-php: ^4
• zrnik/php-attribute-reflection: ^0

Requires (Dev)

• php-di/php-di: ^7
• phpstan/phpstan: ^1
• phpunit/phpunit: ^10
• roave/security-advisories: dev-latest
• symplify/easy-coding-standard: ^12
• tracy/tracy: ^2
• zrnik/phpunit-exceptions: ^0.1

proprietary

• Štěpán Zrník

README

"I'm susperd the mountain zweist" - Lenka Dusilová

What is this?

This is a routing tool for Slim Framework 4 to generate router only by using zircote/swagger-php attributes (or maybe annotations, didn't test it) to generate the router.

composer require zrnik/zweist

What do you mean?

1. You annotate your controller methods with the zircote/swagger-php attributes

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. Add ZweistConfiguration to your 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. Generate (and commit) openapi.json & router.json

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

4. Let ZweistRouteService populate routes in the \Slim\App instance.

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

More things you should know

You will need to create a class with openapi description attributes. (see ./tests/ExampleApplication/ExampleApplicationInfo.php)

You want to generate openapi.json and router.json locally when developing, and then committing them with your code, because you do not want to scan all the files for the router at runtime for every request.

You should check on the CI that you didn't forget to generate new files.