getting-started.md

Getting Started

Installation

composer require open-solid/api

If you're using Symfony Flex, the bundle is registered automatically. Otherwise, add it to your config/bundles.php:

return [
    // ...
    OpenSolid\Api\OpenSolidApiBundle::class => ['all' => true],
];

Minimal Configuration

# config/packages/open_solid_api.yaml
open_solid_api:
    paths:
        - '%kernel.project_dir%/src/Controller'

The paths option tells the bundle which directories to scan for controller classes.

Define Your First Endpoint

Create a controller class with a routing attribute:

namespace App\Controller;

use OpenSolid\Api\Routing\Attribute\Get;

#[Get(
    path: '/hello',
    name: 'api_hello',
    description: 'Say hello',
    tags: ['Greeting'],
)]
final readonly class HelloController
{
    public function __invoke(): array
    {
        return ['message' => 'Hello, world!'];
    }
}

The bundle will generate an OpenAPI GET /hello operation from this class automatically.

View the Spec

Import the bundle's route in your project to expose the OpenAPI spec over HTTP:

# config/routes/open_solid_api.yaml
open_solid_api:
    resource: '@OpenSolidApiBundle/config/routes.php'
    prefix: /api  # optional

Then access your spec at:

• JSON: http://localhost:8000/api/docs.json
• YAML: http://localhost:8000/api/docs.yaml

Or export it to a file:

php bin/console openapi:generate openapi.json
php bin/console openapi:generate openapi.yaml

Adding OpenAPI Metadata

Use swagger-php attributes to define top-level metadata such as the API title, version, servers, and tags. Place them on any class within the scanned paths:

namespace App\Controller;

use OpenApi\Attributes as OA;

#[OA\Info(
    version: '1.0',
    description: 'My API description',
    title: 'My API',
)]
#[OA\Server(url: 'https://api.example.com')]
#[OA\Tag(name: 'Product', description: 'Product management')]
class OpenApiSpec
{
}

Next Steps

• Routing Attributes — Learn about all available HTTP method attributes
• Request & Response Handling — Request bodies, response schemas, and the decorator pipeline
• Pagination — Built-in paginated collection support
• Configuration Reference — All configuration options