apigenie-generator server spring (AsyncAPI)
Tier 2 · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · Verification
Generate a Spring Boot application of the Kafka channels of an AsyncAPI document.
Usage
apigenie-generator server spring [...OPTIONS] INPUT_FILE
Description
apigenie-generator server spring generates from OpenAPI documents (see
apigenie-generator server spring) and from AsyncAPI 3.x
documents, telling them apart by their openapi or asyncapi field. Documents referencing other
files are bundled first.
From an AsyncAPI document it generates a Maven project of a Spring Boot 3 application using
Spring for Apache Kafka. By default the application
is the one the document describes: it sends the messages of send operations and receives the
messages of receive operations. Set the perspective option to counterpart to swap them.
The generator has one part per protocol. Today it generates the Kafka channels: the channels of
servers with the kafka or kafka-secure protocol, and channels with a Kafka binding in
documents without servers. Channels of other protocols are skipped and reported as info.
@Component
class LabelFarm implements RequestLabelRenderHandler {
@Override
public RequestLabelRenderReply onRenderLabel(RenderLabel message) {
LabelRenderResult result = render(message.payload());
return new LabelRendered(message.key(), result, new LabelRenderedHeaders(null));
}
}
@Service
class Shipments {
private final PublishShipmentEventsSender events;
void delivered(String shipmentId, ShipmentDeliveredData data, ShipmentDeliveredHeaders headers) {
events.sendShipmentDelivered(new ShipmentDelivered(shipmentId, data, headers));
}
}
The generated code has:
- models (package
model): a record per object schema the messages use, with Jackson and Jakarta Bean Validation annotations (@NotNullfor required properties,@Valid,@Pattern,@Size,@Min/@Max,@DecimalMin/@DecimalMax,@Email); an enum per enumeration; a sealed interface peroneOfof objects (@JsonTypeInfoby thediscriminatorproperty, or by deduction).allOfmembers are merged into one record. Schemas under#/components/schemaskeep their name; inline schemas are named after their message (PlaceOrderPayload) or their owner and property (LabelRenderRequestFormat). - messages (package
messages): a record per message with its Kafkakey, itspayloadand itsheaders, and a headers record with the message’s headers, the headers of its traits merged as AsyncAPI does (JSON Merge Patch: a laterrequiredlist replaces an earlier one). Headers with a constant value, e.g. thece_specversionandce_typeof CloudEvents in binary mode, are constants of the headers record (ShipmentStatusChangedHeaders.CE_TYPE), which senders write and listeners compare. The key is aStringvalidated by the key schema of the Kafka message binding. - Kafka (package
kafka):- for every received operation, a handler interface (
ConsumeOrdersHandler) with anon<Message>method per message, which you implement as a Spring bean, and a listener (ConsumeOrdersListener) with a@KafkaListenermethod. Several messages of a channel are told apart by a payload property or a header with a distinct constant value (e.g.typeorce_type); otherwise the first message whose payload is valid is chosen. Records matching no message go toonUnknown, which ignores them by default. - for every sent operation, a sender (
PublishShipmentEventsSender) with asend<Message>(message)method per message, over aKafkaTemplateusing the operation’s client id. - request/reply operations with a reply channel: the requester’s sender uses a
ReplyingKafkaTemplatelistening on the reply channel’s topic and returnsCompletableFuture<<Operation>Reply>, a sealed interface of the reply messages. Replies are matched by the header of the request message’scorrelationId, generated when the request has none. A replier’s handler returns the reply, which the listener sends to the reply topic with the request’s correlation id copied (from a header or a payload property, as thecorrelationIdlocations say). KafkaJson, converting payloads (JSON) and headers (UTF-8 text) and validating messages, andKafkaTopicsConfiguration, creating the topics of the channels from their Kafka bindings (partitions, replicas,topicConfiguration) whenasyncapi.kafka.create-topicsistrue.
- for every received operation, a handler interface (
- project files:
pom.xml(parentspring-boot-starter-parent,spring-boot-starter,spring-boot-starter-json,spring-boot-starter-validation(withbean_validation),spring-kafka, and the test starters), the@SpringBootApplicationclass andsrc/main/resources/application.yaml.
application.yaml points spring.kafka.bootstrap-servers to the first Kafka server (server
variables replaced by their default) and configures String keys and byte array values. The
asyncapi.kafka section holds every Kafka server, the topic of every channel and the group and
client ids of every operation, which the generated code reads, so that they can be changed without
regenerating:
asyncapi:
kafka:
create-topics: false
servers:
production-kafka:
bootstrap-servers: kafka-eu.events.carpetexpress.example:9093
schema-registry-url: https://schemas.events.carpetexpress.example
channels:
shipment-events:
topic: carpetexpress.shipment-events.v2
operations:
consume-carrier-scans:
group-id: tracking-ingest
client-id: carpet-express-consume-carrier-scans
Security
Each SASL or client certificate scheme of the Kafka servers gets a Spring profile named after its
key in kebab case, e.g. kafka-scram for kafkaScram, as a document of application.yaml. Start
the application with the profile (--spring.profiles.active=kafka-scram) to connect with the
scheme; without one, it connects without security. The credentials come from environment
variables named after the scheme key, e.g. KAFKA_SCRAM_USERNAME and KAFKA_SCRAM_PASSWORD:
| Scheme | Profile settings |
|---|---|
scramSha256, scramSha512 |
spring.kafka.security.protocol SASL_SSL (SASL_PLAINTEXT on kafka servers), sasl.mechanism and a ScramLoginModule sasl.jaas.config with <KEY>_USERNAME and <KEY>_PASSWORD |
plain, userPassword |
the same with PLAIN and PlainLoginModule |
X509 |
spring.kafka.security.protocol SSL and an SSL bundle (spring.kafka.ssl.bundle) of the PEM files <KEY>_CERT (the client certificate), <KEY>_KEY (its private key) and <KEY>_CA |
A scheme shared by servers with different protocols gets one profile, with the protocol of the first of them, and a warning names both servers.
---
spring:
config:
activate:
on-profile: kafka-scram
kafka:
security:
protocol: SASL_SSL
properties:
sasl.mechanism: SCRAM-SHA-512
sasl.jaas.config: org.apache.kafka.common.security.scram.ScramLoginModule required username="${KAFKA_SCRAM_USERNAME}" password="${KAFKA_SCRAM_PASSWORD}";
Other scheme types, such as gssapi, are left out with a warning.
Avro payloads
A message whose schemaFormat is an Avro one (application/vnd.apache.avro;version=1.9.0, with
or without +json or +yaml) carries the Avro class of its record schema as its payload. The
schema is written to src/main/avro/<full name>.avsc and the avro-maven-plugin generates the
class (strings as String) when the project builds. A schema without a namespace gets
<base package>.avro; a root schema that isn’t a record is skipped with a warning.
The generated KafkaAvro bean encodes and decodes the payloads in Avro’s binary encoding, with
the id of the writer’s schema where the Kafka binding of the message says: before the payload
(schemaIdLocation: payload, Confluent’s wire format) or in the apicurio.value.globalId
header (schemaIdLocation: header). Senders get the id from a schema registry, by the subject
of schemaLookupStrategy (TopicIdStrategy, {topic}-value, by default):
- a
KafkaAvro.SchemaRegistrybean, when the application defines one; - otherwise the Confluent-compatible registry at the
schema-registry-urlof the first Kafka server, with the basic authentication ofasyncapi.kafka.schema-registry.usernameandpassword. It registers each schema once withPOST /subjects/{subject}/versions.
@Bean
KafkaAvro.SchemaRegistry schemaRegistry() {
return KafkaAvro.confluent("https://schemas.events.carpetexpress.example", "ingest", System.getenv("REGISTRY_PASSWORD"));
}
Listeners decode records with the schema of the generated class, so the writer’s schema must be
the same. A record that isn’t a payload of it fails with an IllegalArgumentException, or goes to
onUnknown when the channel has several messages. A correlation id at a payload
pointer of an Avro message is left out with a warning.
Group and client ids come from the groupId and clientId schemas of the Kafka operation
bindings, of the operation or its traits: their const, single enum value, default or first
example. Without a value, <artifact id>-<operation> is used, with a comment naming the
binding’s pattern.
Constraints Bean Validation can’t express are line comments of the record or component: draft-07
dependencies, if/then/else, not, tuples (items arrays, mapped to List with @Size),
patternProperties, const values, and anyOf/oneOf branches constraining the properties of
an object.
Not supported, and reported as warnings: payloads of non-JSON schema formats other than Avro
(Protobuf, RAML) (the messages are skipped, and operations left without a message too), reply
addresses given by runtime expressions, Kafka topics with parameters, and security schemes other
than plain, scramSha256, scramSha512, userPassword and X509 (such as gssapi). With a
correlation id in the payload, the replier’s reply must carry the property (the listener overwrites
it with the request’s), and a requester matches replies by the kafka_correlationId header, which
the replier must copy.
Extensions
| Extension | Effect |
|---|---|
x-apigenie.codegen.name |
name of the class of a schema |
x-apigenie.codegen.disabled |
true on a channel or an operation leaves it out (with the operations of a channel left out) |
The extensions can live in an overlay for this target instead of in the document, e.g.
spring.overlay.yaml:
overlay: 1.0.0
info:
title: Java names
version: 1.0.0
actions:
- target: $.components.schemas.Order
update:
x-apigenie:
codegen:
name: PurchaseOrder
apigenie-generator server spring asyncapi.yaml --overlay spring.overlay.yaml -o out
Options
-c, –config
Path to the configuration file to use. See the “Configuration” section for more information.
–overlay OVERLAY
Path to an OpenAPI Overlay (1.0 to 1.2) applied to the input before generating, e.g. one setting the
extensions of the “Extensions” section. Can be repeated: the overlays apply in order, after those
listed under commands.generate.server_spring.overlay in the configuration file (with paths
relative to it). Warnings and errors about a value an overlay set point to the overlay. The overlays
apply to the AsyncAPI document bundled with the files it references.
–strict
Makes an overlay action whose target selects nothing an error (exit status 2, nothing is generated)
instead of a warning (OVERLAY:LINE:COL: action #N (TARGET) selects no nodes.).
–check
Writes nothing: compares what the generator would write with the output directory, prints the files that would be created or changed, and exits with 1 when there are any (since 0.12.0). See Check that generated code is up to date.
-o, –output
Directory where the project is generated.
–package-name
Maven artifact id of the project. Defaults to the title of the API in kebab case. The base package
defaults to com.example. followed by the artifact id in lower case without other characters than
letters and digits (prefixed with app when it starts with a digit or is a Java keyword).
–package-version
Version of the project. Defaults to the version of the API.
-p, –property
Applies to OpenAPI documents only; using it with an AsyncAPI document is an error.
Configuration
The options are read from the asyncapi section of the configuration of apigenie-generator server spring;
its other keys configure the generation from OpenAPI documents.
version: '1.0'
commands:
generate:
server_spring:
asyncapi:
base_package: com.acme.events
group_id: com.acme
java_version: 21
spring_boot_version: 3.3.13
bean_validation: true
perspective: application
| Option | Description |
|---|---|
base_package |
Package of the generated code (default: com.example.<artifact id>); models are in .model, messages in .messages, the Kafka code in .kafka |
group_id |
Maven group id (default: the base package) |
java_version |
Java release, 17 (default) or later |
spring_boot_version |
Version of the Spring Boot 3 parent (default 3.3.13) |
bean_validation |
true (default): Bean Validation annotations, and validation of sent and received messages; false: none |
perspective |
application (default): the described application; counterpart: its counterpart, receiving what it sends |
Verification
The codegen conformance suite runs this target on the Carpet Express AsyncAPI fixture. Level 1 compares the output with its snapshots and checks each feature, Level 2 runs the language's type checker and linter, and Level 3 runs the generated code in contract tests against the fixture. All targets.
This target's support tier is Tier 2. It goes through all three levels before every release, like Tier 1. It doesn't aim to support every feature: a feature of the fixture can stay unsupported, with the reason its manifest gives.
| Results | Level 1 | Level 2 | Level 3 |
|---|---|---|---|
| Release 0.12.0 | ✓ snapshots of 3.0; 31 supported, 0 not yet | ✓ pass (openjdk version "21.0.13" 2026-10-20 LTS, Apache Maven 3.10.0) | ✓ 5 of 5 operations pass (openjdk version "21.0.13" 2026-10-20 LTS, Apache Maven 3.10.0) |
| Development version | ✓ snapshots of 3.0; 31 supported, 0 not yet | runs before a release | runs before a release |