DEV Community: Antonio Turdo

Your Symfony events have a contract: generate the AsyncAPI docs from your code

Antonio Turdo — Thu, 02 Jul 2026 05:58:12 +0000

A Symfony app that exposes an HTTP API can have that API documented directly from the code: tooling reads the controllers and routes and produces an OpenAPI spec. The framework knows every endpoint, so the documentation is derived from the code rather than maintained alongside it.

Event-driven systems have contracts too, which messages flow, what their payload looks like, where they go, but nothing in the framework enumerates them. No generator reads the messages off the framework the way it reads HTTP routes, so often the contract is either left undocumented or written and maintained by hand.

AsyncAPI is the standard that fills the gap: like OpenAPI, but for messages over a broker (AMQP, Kafka, SQS, …) instead of REST APIs. zeusi/asyncapi-bundle is a Symfony bundle that generates AsyncAPI 3.x documentation from your application's code.

What an AsyncAPI document describes

An AsyncAPI document captures, in a machine-readable spec:

messages, the events/commands that flow, each with a payload schema;
channels, the addressable medium they flow through;
operations, whether your app sends or receives each message;
servers, the brokers involved, and their protocol.

Once it exists, you get the same things OpenAPI gives you for REST: a browsable UI, a contract consumers can code against, schema validation, and a single source of truth that can live next to the code.

Why events are harder to document than a REST API

REST tooling has a natural anchor: routes. Every endpoint is registered with the framework, so a generator can enumerate controllers and reflect their input/output. There's a definitive list to walk.

An event-driven app has no equivalent. A message might reach the broker through a client library, a vendor SDK, or a plain HTTP call, there's no single point the framework owns, so nothing holds a registry that says "these are the events this service publishes, and this is their shape". AsyncAPI itself doesn't impose one either. So the document is either written by hand and kept in sync manually, or derived from a convention the tooling can read.

This bundle takes the pragmatic route, on one assumption: that each message is represented by a PHP class, a DTO. The class is the anchor: the payload schema is derived from it, so the documentation can't drift from the code. The remaining question, which classes are messages, is answered, by default, with an attribute on the class, which also carries the metadata the code can't infer, like the channel a message belongs to.

Installation and setup

composer require zeusi/asyncapi-bundle

Minimal configuration is just your document's info:

# config/packages/asyncapi.yaml
asyncapi:
  document:
    info:
      title: 'Demo Events'
      version: '1.0.0'

And the routes for the two endpoints (more on those below):

# config/routes/asyncapi.yaml
asyncapi:
  resource: '@AsyncApiBundle/Controller/AsyncApiController.php'
  type: attribute

That's the whole setup. Now let's document something.

Declaring a message

Mark the DTO that represents your event with #[AsyncApiMessage]:

use Zeusi\AsyncApiBundle\Attribute\AsyncApiMessage;

#[AsyncApiMessage(channel: 'bookings', summary: 'A trip was booked', tags: ['travel'])]
final class TripBooked
{
    public function __construct(
        public readonly string $bookingId,
        public readonly int $travelers,
    ) {
    }
}

The bundle scans your code for the attribute, derives each payload schema from the class, and assembles a valid AsyncAPI 3.x document: a message in components.messages, grouped into a channel, with a send operation.

The schema derivation is handled by zeusi/json-schema-extractor: it reflects the class and asks a serialization strategy how the object goes over the wire. With the Symfony Serializer strategy (used when the Serializer is available), the schema reflects the shape you actually send, serialization groups, #[SerializedName], name converters, discriminators. PHPDoc and Validator constraints enrich it further when those packages are present.

The attribute carries only the things the code can't tell you, placement and human metadata (title, summary, tags, …). Everything structural comes from the class. Because the schema is derived, it can't fall out of sync with the DTO.

Exposing the document and UI

The bundle exposes:

GET /asyncapi.json, the generated document as JSON. Always available, and the thing your consumers (or a contract test) actually fetch.
GET /asyncapi, an HTML UI rendered with the official AsyncAPI web component, so humans get a browsable view (this one needs Twig, install symfony/twig-bundle to enable it).

That's the attribute workflow end to end: annotate the events, get a contract.

The Symfony Messenger integration

Symfony has no first-class notion of "a published event" to hook into. The closest thing is Messenger, it's where transports, routing and serialization are already declared, which makes it the one sensible anchor in the ecosystem. So the bundle can read your Messenger setup to fill in the parts of the document that live in your infrastructure, not in your DTOs.

It reuses Messenger's own routing semantics, the same type matching Messenger uses to pick a transport for a message, so what it documents matches where your messages actually go. There are two capabilities, both opt-in, configured under providers.messenger:

asyncapi:
  providers:
    messenger:
      transports: ['events']   # allowlist; scopes everything below
      enrichment: true
      discovery: false

Enrichment: servers and content types

With enrichment: true, for each documented message routed to a transport the bundle adds:

servers, derived from the transport DSN (host + protocol);
content type, taken from the transport's serializer (the Symfony Serializer yields application/json), unless the message declared one;
channel ↔ server links, when more than one server exists, so each channel is pinned to the servers its messages actually use.

Internal transports (sync://, in-memory://, doctrine://) and failure/retry transports are left out automatically.

Discovery: messages from the routing map

With discovery: true, the routing map itself becomes a source of messages, so classes you've already routed don't need the attribute at all:

# config/packages/messenger.yaml
framework:
  messenger:
    routing:
      'App\Message\TripBooked': events   # already here for your app to work

The bundle treats the routing keys (and classes matched by interface, parent or namespace-wildcard rules) as messages, deriving their payloads from the class just like the attribute path does. The * catch-all is never a source, it matches every dispatched object and can't be enumerated, and anything you did annotate stays owned by the attribute, so its richer metadata wins.

Why the integration is opt-in

Both capabilities rest on an assumption: that the Messenger transports are the publication channel. That doesn't always hold. Messenger might be used purely for internal queues, async jobs that never leave the app, or a message might pass through an internal Messenger queue and then be published by some other mechanism the bundle can't see. In either case, documenting the Messenger transport as a public server would be misleading.

The payload extraction follows from the code and makes no assumption about how you publish. The Messenger integration, by contrast, makes a semantic guess, and a guess that can write wrong information into a public contract should be a conscious choice, not a default. Turning it on is your assertion that, for the documented transports, Messenger is how the event goes out. The transports allowlist is there to scope it precisely.

Conclusion

Generating documentation from code is what keeps it from going stale, and this bundle applies that idea to the messages a service publishes in a distributed system. Payload schemas come from your DTOs; messages are discovered from an attribute or from your Messenger configuration, which the bundle can also read to derive the brokers involved. The documentation moves when the code moves, instead of being a separate artifact to maintain.

The bundle is young, pre-1.0, so the API may still shift between minor versions.
The attribute-based workflow is the stable core, while the Messenger integration is there to draw on when it makes sense for your system.

Package: zeusi/asyncapi-bundle
Source & docs: github.com/antonioturdo/asyncapi-bundle

If you document events by hand today, give it a try, and if it's missing something your setup needs, issues and PRs are welcome.

Generating JSON Schema from PHP DTOs with Symfony Serializer awareness

Antonio Turdo — Sun, 07 Jun 2026 19:08:20 +0000

A PHP project that serializes and deserializes DTOs often needs a JSON Schema for them — for an LLM's structured output, for API documentation, or to validate incoming payloads.

Writing it by hand works until the code changes. With Symfony Serializer, the JSON shape can shift without the PHP types changing at all — a new serialization group, a #[SerializedName], a discriminator — and the hand-written schema no longer matches what the serializer produces.

json-schema-extractor is a PHP library that generates JSON Schema from DTOs by reading the metadata they already carry — native types, PHPDoc, and serializer configuration — so the schema stays in sync with the code. It supports plain json_encode/JsonSerializable and Symfony Serializer; this article focuses on the latter.

The problem in concrete terms

Take a simple DTO:

final class OrderSummary
{
    public function __construct(
        #[Groups(['public'])]
        #[SerializedName('order_id')]
        public readonly string $id,

        #[Groups(['public'])]
        public readonly Money $total,

        #[Groups(['internal'])]
        public readonly string $internalNote,
    ) {}
}

When Symfony Serializer renders this with the public group, the JSON output is:

{ 
  "order_id": "ORD-1042", 
  "total": { 
    "amount": 4999, 
    "currency": "EUR" 
  } 
}

internalNote is absent. id is renamed. total is a nested object. A hand-written schema that matches this needs to know about groups, serialized names, and how Money is normalized. If any of those change, you update them in two places.

How the library works

The extraction pipeline has four phases, each with a clear responsibility:

1. Discover — ReflectionDiscoverer reads the class with reflection: property names, native PHP types, visibility. No dependencies required.

2. Enrich — one or more enrichers augment the PHP model with metadata reflection alone can't see. PhpStanEnricher and PhpDocumentorEnricher both read PHPDoc (@var list<string>, @var array{name: string, age: int}, generics, descriptions, deprecation), via different parsers. SymfonyValidationEnricher maps Symfony Validator constraints (NotBlank, Length, Range…) to their JSON Schema equivalents — appropriate when the application actually validates the objects against those constraints, so the schema's guarantees hold for the real data. Enrichers are optional and composable.

3. Project — a serialization strategy converts the enriched PHP model into the serialized shape: the JSON-facing view of the class. The Symfony Serializer support is implemented in this phase.

4. Map — StandardJsonSchemaMapper folds the projected shape into a JSON Schema document, handling $ref, reusable definitions, dialect (draft-7 or 2020-12), and union semantics.

The four phases are wired together by SchemaExtractor, the entry point you call to produce a schema.

Each phase is defined by an interface — DiscovererInterface, EnricherInterface, SerializationStrategyInterface, JsonSchemaMapperInterface — so every component can be swapped or extended. You can plug in your own discoverer, enricher, strategy, or mapper without touching the rest.

Installation

Install the library, then add only the optional packages your chosen components need:

composer require zeusi/json-schema-extractor

# optional, depending on what you enable:
composer require phpstan/phpdoc-parser              # for PhpStanEnricher
composer require phpdocumentor/reflection-docblock  # for PhpDocumentorEnricher
composer require symfony/validator                  # for SymfonyValidationEnricher
composer require symfony/serializer                 # for SymfonySerializerStrategy

The core package itself has no mandatory dependencies.

A minimal extractor

use Zeusi\JsonSchemaExtractor\Discoverer\ReflectionDiscoverer;
use Zeusi\JsonSchemaExtractor\Enricher\PhpStanEnricher;
use Zeusi\JsonSchemaExtractor\Mapper\StandardJsonSchemaMapper;
use Zeusi\JsonSchemaExtractor\SchemaExtractor;
use Zeusi\JsonSchemaExtractor\Serialization\JsonEncodeSerializationStrategy;

$extractor = new SchemaExtractor(
    new ReflectionDiscoverer(),
    [new PhpStanEnricher()],
    new JsonEncodeSerializationStrategy(),
    new StandardJsonSchemaMapper(),
);

$schema = $extractor->extract(OrderSummary::class);

This gives you a schema based on native PHP types and PHPDoc. JsonEncodeSerializationStrategy is the right choice when your JSON is produced by json_encode() or JsonSerializable (in that case, the shape is read from jsonSerialize()'s return type and PHPDoc, since its body is opaque to static analysis).

For Symfony Serializer, you swap the strategy.

Adding Symfony Serializer awareness

To make the schema follow Symfony Serializer instead of json_encode(), swap in SymfonySerializerStrategy. Runtime serializer context — serialization groups, for example — is passed to extract() through an ExtractionContext, which is optional:

use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory;
use Symfony\Component\Serializer\Mapping\Loader\AttributeLoader;
use Zeusi\JsonSchemaExtractor\Context\ExtractionContext;
use Zeusi\JsonSchemaExtractor\Context\SymfonySerializerContext;
use Zeusi\JsonSchemaExtractor\Serialization\SymfonySerializerStrategy;

$strategy = new SymfonySerializerStrategy(
    new ClassMetadataFactory(new AttributeLoader()),
);

$extractor = new SchemaExtractor(
    new ReflectionDiscoverer(),
    [new PhpStanEnricher()],
    $strategy,
    new StandardJsonSchemaMapper(),
);

// Optional: a context carrying the runtime serializer settings (here, the "public" group).
$context = (new ExtractionContext())->with(new SymfonySerializerContext([
    'groups' => ['public'],
]));

$schema = $extractor->extract(OrderSummary::class, $context);

For OrderSummary with the public group, the schema matches what Symfony Serializer produces: internalNote is absent, and id appears as order_id.

The strategy reads the same inputs Symfony Serializer reads at runtime — both the attributes declared on the DTO and the options passed in the serializer context (the array shown above, where groups lives):

#[SerializedName] / name converters → property keys are renamed in the schema.
Serialization groups (groups context option) → only properties in the selected groups appear.
ignored_attributes (context option) → the listed properties are excluded.
attributes (context option) → restricts the schema to the listed attributes, with per-property nested views for class-backed ones.
Discriminator maps (#[DiscriminatorMap]) → a base type expands to a oneOf over its mapped subtypes, each tagged with the discriminator field; a concrete subtype is a single object with that field fixed to its key.
Known normalizers (by type) → DateTimeInterface becomes { type: string, format: date-time }, Symfony UIDs become { type: string, format: uuid }, and so on.
skip_null_values (context option) → nullable properties become optional in the schema.

What it does not model

The strategy reads static metadata — attributes and types — so it cannot mirror everything Symfony Serializer does at runtime. It is not a 1:1 mapping of the serializer's behaviour. The gaps worth knowing about:

preserve_empty_objects (context option) → serializes an empty collection as {} instead of []; whether it applies depends on the runtime value, which static analysis can't see.
skip_uninitialized_values (context option) → omits typed properties that were never assigned; that's a fact about the object instance at runtime, not about the class.
Custom normalizers outside the known set → their output shape is defined in application code, so it can't be inferred.
max_depth_handler / circular_reference_handler (context options) → callables that replace a node when the depth limit or a cycle is hit; their output is arbitrary application code.
#[MaxDepth] → not modeled as a tightened schema, and doesn't need to be: recursion is already broken with a $ref, and a depth-bounded payload is a valid instance of that (looser) recursive schema.
Interfaces / polymorphic base types → an interface has no single concrete shape, so it can't be resolved on its own. A Symfony #[DiscriminatorMap] turns it into a oneOf when the payload carries a type field; otherwise a custom strategy or enricher can supply the concrete shapes.

When a case isn't covered, the serialization strategy is the extension point: implement SerializationStrategyInterface, or decorate SymfonySerializerStrategy, and handle it there.

Reusable definitions and $ref

By default, class-backed nested types are emitted once under definitions (Draft-7) or $defs (2020-12) and referenced with $ref everywhere they are used. If you prefer the nested schemas expanded at the point of use instead, switch to ClassReferenceStrategy::Inline:

use Zeusi\JsonSchemaExtractor\Mapper\ClassReferenceStrategy;
use Zeusi\JsonSchemaExtractor\Mapper\StandardJsonSchemaMapper;
use Zeusi\JsonSchemaExtractor\Mapper\StandardJsonSchemaMapperOptions;

$mapper = new StandardJsonSchemaMapper(new StandardJsonSchemaMapperOptions(
    classReferenceStrategy: ClassReferenceStrategy::Inline,
));

Circular references are handled automatically either way: a self-referential class produces a $ref back to the root (#) or to the relevant definition, rather than an infinite expansion.

Symfony Bundle

If you use the Symfony framework, a bundle registers the built-in components as services and wires the extractor into the container. Its main convenience is reusing the Symfony Serializer and Validator services your application already has — so you don't assemble a ClassMetadataFactory, a validator, and the strategy/enricher wiring by hand.

You declare one or more extractor pipelines, choosing the strategy that matches how your app serializes:

# config/packages/json_schema_extractor.yaml
json_schema_extractor:
  default_extractor: api
  extractors:
    api:
      enrichers:
        - json_schema_extractor.enricher.phpstan
      serialization: json_schema_extractor.serialization.symfony_serializer

SchemaExtractor is aliased to the default extractor, so you inject it directly:

public function __construct(
    private readonly SchemaExtractor $extractor,
) {}

// ...
$schema = $this->extractor->extract(OrderSummary::class);

See the bundle documentation for multiple pipelines, custom services, and the debug command.

Use case: structured output for LLMs

A common use today is structured output from an LLM. Most providers accept a JSON Schema as the contract for the model's response: you generate the schema from a DTO, send it with the request, and deserialize the response back into that same DTO.

Since the schema comes from the DTO you deserialize into, the two stay in sync as the DTO changes.

Resources

The library is open source under the MIT license: github.com/antonioturdo/json-schema-extractor. The documentation covers all enrichers, serialization strategies, mapper options, and the Symfony bundle in detail.

If you are building something with it — structured output pipelines, AsyncAPI documentation, API contract testing — feedback and contributions are welcome.