PHP code example of spiral-packages / swagger-php

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

spiral-packages / swagger-php example snippets

protected const LOAD = [
    // ...
    \Spiral\OpenApi\Bootloader\SwaggerBootloader::class,
];

use Spiral\OpenApi\Config\SwaggerConfig;
use Spiral\OpenApi\Generator\Parser\ConfigurationParser;
use Spiral\OpenApi\Generator\Parser\OpenApiParser;
use Spiral\OpenApi\Renderer\HtmlRenderer;
use Spiral\OpenApi\Renderer\JsonRenderer;
use Spiral\OpenApi\Renderer\YamlRenderer;

return [
    'documentation' => [
        'info' => [
            'title' => 'My App',
            'description' => 'API documentation',
            'version' => '1.0.0',
        ],
    ],
    'parsers' => [
        ConfigurationParser::class,
        OpenApiParser::class,
    ],
    'renderers' => [
        JsonRenderer::FORMAT => JsonRenderer::class,
        YamlRenderer::FORMAT => YamlRenderer::class,
        HtmlRenderer::FORMAT => HtmlRenderer::class,
    ],
    'paths' => [
        directory('app'),
    ],
    'exclude' => null,
    'pattern' => null,
    'version' => null,
    'cache_key' => SwaggerConfig::DEFAULT_CACHE_KEY,
    'generator_config' => [
        'operationId' => [
            'hash' => true,
        ],
    ],
    'use_cache' => env('APP_ENV') === 'prod',
];

namespace App\Entity;

use OpenApi\Attributes as OA;

#[OA\Schema(
    schema: 'User',
    description: 'User record',
    ty: 'first_name', type: 'string')]
    public string $firstName;

    #[OA\Property(property: 'last_name',type: 'string')]
    public string $lastName;
}

use OpenApi\Attributes as OA;
use Psr\Http\Message\ResponseInterface;

class UserController
{
    #[OA\Get(
        path: '/api/v1/users',
        tags: ['User'],
        parameters: [
            new OA\Parameter(ref: '#/components/parameters/page'),
            new OA\Parameter(ref: '#/components/parameters/limit'),
            new OA\Parameter(
                name: 'sort',
                description: 'The field used to order users',
                in: 'query',
                schema: new OA\Schema(type: 'string'),
                examples: [
                    'user.first_name' => new OA\Examples(
                        example: 'user.first_name',
                        summary: 'Sort by `user.first_name` field',
                        value: 'user.first_name'
                    ),
                    'user.last_name' => new OA\Examples(
                        example: 'user.last_name',
                        summary: 'Sort by `user.last_name` field',
                        value: 'user.last_name'
                    ),
                ]
            ),
            new OA\Parameter(ref: '#/components/parameters/direction')
        ],
        responses: [
            new OA\Response(
                response: 200,
                description: 'Retrieve a collection of users',
                content: new OA\JsonContent(
                    properties: [
                        new OA\Property(
                            property: 'meta',
                            ref: '#/components/schemas/ResponseCollectionMeta'
                        ),
                        new OA\Property(
                            property: 'data',
                            description: 'Collection of users',
                            type: 'array',
                            items: new OA\Items(type: 'array', items: new OA\Items(
                                properties: [
                                    new OA\Property(
                                        property: 'uuid',
                                        type: 'string',
                                        example: '7be33fd4-ff46-11ea-adc1-0242ac120002'
                                    ),
                                    new OA\Property(
                                        property: 'type',
                                        type: 'string'
                                    ),
                                    new OA\Property(
                                        property: 'attributes',
                                        ref: '#/components/schemas/User'
                                    ),
                                ],
                                type: 'object'
                            ))
                        ),
                    ],
                    type: 'object'
                )
            ),
        ]
    )]
    public function list(): ResponseInterface
    {
        // ...
    }
}

// file app/config/swagger.php
return [
    'documentation' => [
        'info' => [
            'title' => 'My App',
            'description' => 'My App API Documentation',
            'version' => '1.0.0'
        ],
        'components' => [
            'parameters' => [
                'page' => [
                    'name' => 'page',
                    'in' => 'query',
                    'example' => 1,
                    'schema' => [
                        'type' => 'integer'
                    ]
                ],
                'limit' => [
                    'name' => 'limit',
                    'in' => 'query',
                    'example' => 25,
                    'schema' => [
                        'type' => 'integer'
                    ]
                ],
                'direction' => [
                    'name' => 'direction',
                    'in' => 'query',
                    'schema' => [
                        'type' => 'string'
                    ],
                    'examples' => [
                        'asc' => [
                            'value' => 'asc',
                            'summary' => 'Sort Ascending'
                        ],
                        'desc' => [
                            'value' => 'desc',
                            'summary' => 'Sort Descending'
                        ]
                    ]
                ]
            ],
            'schemas' => [
                'ResponseCollectionMeta' => [
                    'type' => 'object',
                    'properties' => [
                        'size' => [
                            'type' => 'integer'
                        ],
                        'page' => [
                            'type' => 'integer'
                        ],
                        'total' => [
                            'type' => 'integer'
                        ]
                    ]
                ]
            ]
        ]
    ],
];

use Spiral\OpenApi\Controller\DocumentationController;

final class RoutesBootloader extends BaseRoutesBootloader
{
    protected function defineRoutes(RoutingConfigurator $routes): void
    {
        // ...

        $routes
            ->add('swagger-api-html', '/api/docs')
            ->action(DocumentationController::class, 'html');
        $routes
            ->add('swagger-api-json', '/api/docs.json')
            ->action(DocumentationController::class, 'json');
        $routes
            ->add('swagger-api-yaml', '/api/docs.yaml')
            ->action(DocumentationController::class, 'yaml');

       // ...
    }
}

bash
composer