README

Symfony bundle that auto-generates OpenAPI 3.0.1 documentation for applications built on the Action-Domain-Responder (ADR) pattern. Works by scanning PHP source files for action classes annotated with #[Operation] and #[Route] attributes — no YAML configuration required.

Features

Zero-config documentation generation from PHP attributes
Automatic schema inference from Symfony Form types (including validation constraints → OpenAPI constraints)
Automatic schema inference from View classes (ViewInterface, IterableView)
Automatic schema inference from plain DTO classes
BackedEnum properties → enum values in schemas
Uuid/Ulid → { type: string, format: uuid }
DateTime/DateTimeImmutable → { type: string, format: date-time }
GET/DELETE/HEAD requests: form fields automatically expanded as query parameters
Recursive schema detection (cycle guard)
Security via #[IsGranted] — no extra annotation needed

Requirements

PHP 8.5+
Symfony 8.x
chamber-orchestra/view-bundle

Installation

composer require chamber-orchestra/openapi-doc-bundle

return [
    // ...
    ChamberOrchestra\OpenApiDocBundle\OpenApiDocBundle::class => ['all' => true],
];

Configuration

proto.yaml

Create a proto.yaml file in your project root. This file is merged into the final output and must contain securitySchemes for security annotations to appear in the generated documentation:

# proto.yaml
components:
    securitySchemes:
        BearerAuth:
            type: http
            scheme: bearer
            bearerFormat: JWT

    # Shared response references (used as string refs in #[Operation])
    responses:
        Unauthorized:
            description: Unauthorized
        NotFound:
            description: Not found
        Forbidden:
            description: Forbidden

    # Additional schemas not generated from code
    schemas:
        Error:
            type: object
            properties:
                message:
                    type: string

Note: Without securitySchemes in proto.yaml, #[IsGranted] annotations are silently ignored and operations appear as public in the generated documentation.

Usage

1. Annotate action classes

Each invokable action class needs #[Route] and #[Operation]:

use ChamberOrchestra\OpenApiDocBundle\Attribute\Operation;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Security\Http\Attribute\IsGranted;

#[Route('/users/{id}', methods: ['GET'])]
#[IsGranted('ROLE_USER')]
#[Operation(
    description: 'Get a user by ID',
    responses: [UserView::class],
)]
class GetUserAction
{
    public function __invoke(): UserView
    {
        // ...
    }
}

2. POST/PUT/PATCH — request body from a Form

#[Route('/users', methods: ['POST'])]
#[IsGranted('ROLE_ADMIN')]
#[Operation(
    description: 'Create a new user',
    request: CreateUserForm::class,
    responses: [UserView::class],
)]
class CreateUserAction
{
    public function __invoke(): UserView { /* ... */ }
}

The form fields are read at generation time and become the requestBody schema. Symfony validation constraints are mapped to OpenAPI constraints:

Constraint	OpenAPI
`NotBlank`	`required: [field]` at schema level
`Length(min, max)`	`minLength`, `maxLength`
`Range(min, max)`	`minimum`, `maximum`
`Positive`	`minimum: 1`
`GreaterThanOrEqual(n)`	`minimum: n`
`Count(min, max)`	`minItems`, `maxItems` (array fields)
`Email`	`format: email`
`Url`	`format: uri`
`ChoiceType(choices)`	`enum` values

Form example

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
use Symfony\Component\Form\Extension\Core\Type\EmailType;
use Symfony\Component\Form\Extension\Core\Type\IntegerType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\Validator\Constraints as Assert;

class CreateUserForm extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('name', TextType::class, [
                'constraints' => [
                    new Assert\NotBlank(),
                    new Assert\Length(min: 2, max: 100),
                ],
            ])
            ->add('email', EmailType::class, [
                'constraints' => [new Assert\NotBlank(), new Assert\Email()],
            ])
            ->add('age', IntegerType::class, [
                'required' => false,
                'constraints' => [new Assert\Range(min: 18, max: 120)],
            ])
            ->add('role', ChoiceType::class, [
                'choices' => ['User' => 'user', 'Admin' => 'admin', 'Moderator' => 'moderator'],
                'constraints' => [new Assert\NotBlank()],
            ]);
    }
}

This generates the following OpenAPI schema:

CreateUserForm:
    type: object
    required: [name, email, role]
    properties:
        name:
            type: string
            minLength: 2
            maxLength: 100
        email:
            type: string
            format: email
        age:
            type: integer
            minimum: 18
            maximum: 120
        role:
            type: string
            enum: [user, admin, moderator]

Nested form (sub-form as object)

class AddressForm extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('street', TextType::class, ['constraints' => [new Assert\NotBlank()]])
            ->add('city', TextType::class, ['constraints' => [new Assert\NotBlank()]])
            ->add('zip', TextType::class);
    }
}

class CreateOrderForm extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('title', TextType::class, ['constraints' => [new Assert\NotBlank()]])
            ->add('address', AddressForm::class);  // nested form → $ref
    }
}

Generated schema:

CreateOrderForm:
    type: object
    required: [title]
    properties:
        title:
            type: string
        address:
            $ref: '#/components/schemas/AddressForm'

AddressForm:
    type: object
    required: [street, city]
    properties:
        street:
            type: string
        city:
            type: string
        zip:
            type: string

Collection of sub-forms

use Symfony\Component\Form\Extension\Core\Type\CollectionType;

class CreateInvoiceForm extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('number', TextType::class, ['constraints' => [new Assert\NotBlank()]])
            ->add('lines', CollectionType::class, [
                'entry_type' => InvoiceLineForm::class,
                'constraints' => [new Assert\Count(min: 1)],
            ]);
    }
}

Generated schema:

CreateInvoiceForm:
    type: object
    required: [number]
    properties:
        number:
            type: string
        lines:
            type: array
            minItems: 1
            items:
                $ref: '#/components/schemas/InvoiceLineForm'

3. GET — form fields become query parameters

GET/DELETE/HEAD actions automatically expand form fields into query parameters instead of a request body:

#[Route('/users', methods: ['GET'])]
#[IsGranted('ROLE_USER')]
#[Operation(
    description: 'Search users',
    request: SearchUsersForm::class,
    responses: [UserListView::class],
)]
class SearchUsersAction
{
    public function __invoke(): UserListView { /* ... */ }
}

use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
use Symfony\Component\Form\Extension\Core\Type\IntegerType;
use Symfony\Component\Form\Extension\Core\Type\TextType;

class SearchUsersForm extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('query', TextType::class, ['required' => false])
            ->add('role', ChoiceType::class, [
                'required' => false,
                'choices'  => ['User' => 'user', 'Admin' => 'admin'],
            ])
            ->add('page', IntegerType::class, ['required' => false]);
    }
}

Each field becomes an individual query parameter:

parameters:
    - name: query
      in: query
      schema:
          type: string
    - name: role
      in: query
      schema:
          type: string
          enum: [user, admin]
    - name: page
      in: query
      schema:
          type: integer

4. Multiple responses (including shared references from proto.yaml)

#[Operation(
    description: 'Update user',
    request: UpdateUserForm::class,
    responses: [
        UserView::class,           // Described as a component schema
        '404' => 'NotFound',       // String ref → #/components/responses/NotFound
        '403' => 'Forbidden',      // String ref → #/components/responses/Forbidden
    ],
)]

5. Custom security

Override security for a specific operation (e.g., API key instead of the default Bearer):

#[Operation(
    description: 'Webhook endpoint',
    security: ['ApiKeyAuth' => []],
)]

Disable security for a public endpoint:

#[Operation(
    description: 'Public endpoint',
    security: [],
)]

6. Annotating DTO properties

Use #[Property] to mark a property as required or add arbitrary OpenAPI attributes:

use ChamberOrchestra\OpenApiDocBundle\Attribute\Property;

class UserView
{
    public Uuid $id;
    public string $name;

    #[Property(required: true, attr: ['example' => 'user@example.com'])]
    public ?string $email = null;  // nullable but explicitly required

    #[Property(attr: ['minLength' => 3, 'maxLength' => 50])]
    public string $username;
}

7. Iterable views (lists)

Use #[Type] from chamber-orchestra/view-bundle to specify the item type:

use ChamberOrchestra\ViewBundle\Attribute\Type;
use ChamberOrchestra\ViewBundle\View\IterableView;

class UserListView extends IterableView
{
    #[Type(UserView::class)]
    protected array $entries = [];
}

Generates:

UserListView:
    type: array
    items:
        $ref: '#/components/schemas/UserView'

Generating documentation

php bin/console openapi-doc:generate

Options:

--src         Source directory to scan (default: <project_dir>/src)
--output      Output file path      (default: <project_dir>/doc.yaml)
--proto       Proto YAML file path  (default: <project_dir>/proto.yaml)
--title       API title             (default: "API Documentation")
--doc-version API version string    (default: "1.0.0")

Example:

php bin/console openapi-doc:generate \
  --src src/Api \
  --output public/openapi.yaml \
  --proto proto.yaml \
  --title "My API" \
  --doc-version "2.1.0"

Type mapping reference

PHP types → OpenAPI

PHP type	OpenAPI
`string`	`type: string`
`int`	`type: integer`
`float`	`type: number`
`bool`	`type: boolean`
`array` / `iterable`	`type: array`
`BackedEnum`	`type: string\|integer` + `enum: [...]`
`Uuid` / `Ulid`	`type: string, format: uuid`
`DateTime` / `DateTimeImmutable`	`type: string, format: date-time`
Custom class	`$ref: '#/components/schemas/ClassName'`

Form field types → OpenAPI

Symfony type	OpenAPI
`TextType`	`type: string`
`IntegerType`	`type: integer`
`NumberType`	`type: number`
`CheckboxType`	`type: boolean`
`EmailType`	`type: string, format: email`
`UrlType`	`type: string, format: uri`
`DateType`	`type: string, format: date`
`DateTimeType`	`type: string, format: date-time`
`ChoiceType`	`type: string` + `enum: [...]`
`ChoiceType(multiple: true)`	`type: array, items: { enum: [...] }`
`CollectionType`	`type: array, items: { ... }`
`RepeatedType`	`type: object` with sub-properties
Custom `FormTypeInterface`	`$ref: '#/components/schemas/FormName'`

Architecture

Action class
  └─ Locator           scans src/ for #[Operation] + #[Route]
  └─ OperationDescriber
       └─ SecurityParser    #[IsGranted] → security placeholder
       └─ RouteParser       #[Route]     → path / method / operationId
       └─ OperationParser   #[Operation] → description / request / responses
       └─ ResponseParser    __invoke return type → ComponentDescriber
  └─ ComponentDescriber (lazy, per class)
       └─ FormParser    FormTypeInterface → schema from form fields + constraints
       └─ ViewParser    ViewInterface     → schema from public properties
       └─ ObjectParser  plain DTO         → schema from public properties
  └─ DocumentBuilder
       └─ merge proto.yaml
       └─ resolve 'default' security → first securityScheme
       └─ emit OpenAPI 3.0.1 YAML

Running tests

composer test           # all tests
composer test:unit      # unit tests only
composer test:integration  # integration tests only

License

MIT

chamber-orchestra / openapi-doc-bundle

Maintainers

Package info

Statistics

Security