Download the PHP package chamber-orchestra/openapi-doc-bundle without Composer

OpenAPI ADR Bundle

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
• OpenAPI specification extensions (x-* keys) on request/response schemas via #[Extension]

Requirements

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

Installation

Register the bundle in config/bundles.php:

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:

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]:

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

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

Form example

This generates the following OpenAPI schema:

Nested form (sub-form as object)

Generated schema:

Collection of sub-forms

Generated schema:

3. GET — form fields become query parameters

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

Each field becomes an individual query parameter:

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

5. Custom security

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

Disable security for a public endpoint:

6. Annotating DTO properties

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

7. Iterable views (lists)

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

Generates:

8. Vendor extensions (x-* keys)

Use #[Extension] (repeatable) on a request class (form type, DTO) or response class (view, DTO) to add OpenAPI specification extensions to its generated schema:

Generates:

The extension name must start with x-; values may be any scalar, array, or null.

Notes:

• For property-level extensions, use the existing #[Property(attr: [...])]: #[Property(attr: ['x-faker' => 'email'])].
• GET/DELETE/HEAD request forms are expanded into query parameters and their schema is excluded from the output — extensions declared on such forms are not emitted.
• Extensions declared in proto.yaml remain untouched and merge as usual.

Generating documentation

Options:

Example:

Type mapping reference

PHP types → OpenAPI

Form field types → OpenAPI

Architecture

Running tests

License

MIT