Payload schemas do not tell an integrator where to connect or which credentials the broker requires. Add servers for broker endpoints, security schemes for authentication methods, and bindings for protocol-specific details. These declarations describe your deployment; they do not configure drivers, provision resources, or enforce access.
The snippets use arkoren.dev/core/asyncapi inside the construction callbacks
introduced in Queues and Operations. Keep credentials,
private keys, tokens, and sensitive example values out of every declaration:
the resulting metadata is included in the exported document.
Broker Endpoints
To document the reporting worker’s AMQP broker, add a server in the document callback. Its local ID is separate from the host and protocol:
definition.Server("primary", "broker.example:5672", "amqp", func(listener *asyncapi.ServerBuilder) {
listener.Description("Reporting broker")
listener.ProtocolVersion("0.9.1")
listener.Pathname("/reports")
})The host accepts a host with an optional port, including bracketed IPv6, not a
URL. Schemes, credentials, paths, queries, and fragments are rejected. Use
Pathname for the endpoint path. ProtocolVersion describes the protocol; it
does not negotiate one.
Once a document declares any servers, every channel must explicitly select at
least one. In the existing work channel callback, add:
channel.Servers("primary")If you also declare the completion channel, add its server selection too. With no declared servers, channels can omit this setting for a portable document. Server IDs may be declared later, but unresolved or duplicate selections fail export. Defining a server does not connect to it or inspect its configuration.
Broker Authentication
To describe username/password authentication, register a scheme in the document
callback and select it on the server. Replace the earlier primary declaration
with this one, retaining its optional endpoint metadata if needed:
definition.SecurityScheme("login", asyncapi.RawObject(`{"type":"userPassword"}`))
definition.Server("primary", "broker.example:5672", "amqp", func(listener *asyncapi.ServerBuilder) {
listener.Security("login")
})The scheme describes a method, not a username or password. Configure actual authentication and authorization on your broker and driver separately. The exporter checks supported scheme type names, required fields for common scheme families, and local references. It does not fully validate protocol rules or OAuth flow semantics.
You can declare schemes after their selections. Duplicate scheme IDs and unresolved local references fail export. Raw scheme aliases to local schemes are checked within the security-scheme collection; external references remain opaque and are never fetched.
Requirement Alternatives
If a broker accepts either username/password or a client certificate, register both schemes and select both on the server. This is an alternative to the previous authentication declaration:
definition.SecurityScheme("login", asyncapi.RawObject(`{"type":"userPassword"}`))
definition.SecurityScheme("certificate", asyncapi.RawObject(`{"type":"X509"}`))
definition.Server("primary", "broker.example:5671", "amqps", func(listener *asyncapi.ServerBuilder) {
listener.Security("login", "certificate")
})The server’s security array means login OR certificate, not both.
OperationBuilder.Security likewise lists alternatives within an operation.
Server and operation requirements apply together (AND across the levels);
an operation’s selection does not replace server authentication.
For example, after declaring a separate scheme named publisher, adding
action.Security("publisher") inside a sending operation documents an additional
requirement. It does not authorize that operation or define broker permissions.
Duplicate selections are errors, including across repeated Security calls.
Broker security metadata does not protect the HTTP endpoint that serves this document. Apply separate document access controls before exposing that endpoint.
Protocol Bindings
A binding is a raw protocol-specific object attached to a server, channel, operation, or message. Choose the level defined by that protocol’s binding specification. To describe the reporting work destination as an AMQP queue, add this inside its channel callback:
channel.Binding("amqp", asyncapi.RawObject(`{
"is": "queue",
"queue": {
"name": "production.report-work",
"durable": true
},
"bindingVersion": "0.3.0"
}`))This exports the supplied queue metadata. It does not create the queue, make it
durable, or guarantee durable delivery. Configure and verify the deployed broker
independently; a successful export cannot establish that these details match it.
Server, operation, and message builders also expose Binding for their levels.
Bindings receive only JSON-object syntax checks, protocol-key ID checks, and duplicate-key checks at their own level. Nested references and protocol-specific semantics are opaque. Document graph references and local security aliases are checked separately; they do not turn binding contents into resolved references.
No broker inventory, producer discovery, traffic sampling, or runtime address parameter expansion occurs during export. Keep these declarations aligned with your application’s actual transport and infrastructure configuration.
For endpoint, binding, and security options, see the
asyncapi API reference.