Server

Server #

Overview #

Server is one of the main entities in the AsyncAPI document. It represents a server used by the channels to send and receive messages. The Server is always assigned to a particular protocol, such as Kafka, AMQP, MQTT, etc. Also, it always has a URL to connect to.

The generated server code contains some common methods and fields, and also method to open channels that are bound to this server. By default, the server code is generated in the servers package.

To learn how a server is reflected in implementation code, see the Implementations page.

Minimal example
channels:
  myChannel:
    description: My channel

servers:
  myServer:
    url: 'kafka://localhost:9092'
    protocol: kafka

package servers

func MyServerURL() run.ParamString {
  return run.ParamString{Expr: "kafka://localhost:9092"}
}
func NewMyServer(producer kafka.Producer, consumer kafka.Consumer) *MyServer {
  return &MyServer{
    consumer: consumer,
    producer: producer,
  }
}

type MyServer struct {
  producer kafka.Producer
  consumer kafka.Consumer
}

func (m MyServer) Name() string {
  return "myServer"
}
func (m MyServer) OpenMyChannelKafka(ctx context.Context) (*channels.MyChannelKafka, error) {
  return channels.OpenMyChannelKafka(ctx, m)
}
func (m MyServer) Producer() kafka.Producer {
  return m.producer
}
func (m MyServer) Consumer() kafka.Consumer {
  return m.consumer
}

Document scope #

A server can be defined in two sections in the AsyncAPI document:

  • servers
  • components.servers

Servers in servers produce the code. Servers in components.servers are just reusable objects, that produce the code only being referred somewhere in the servers section. Therefore, if such server is not referred anywhere, it will not be generated at all.

So, in the example below, only the foo and bar are considered, spam will be ignored:

Example
servers:
  foo:  # <-- will be generated
    url: 'kafka://localhost:9092'
    protocol: kafka
  bar:  # <-- will be generated
    $ref: '#/components/servers/barServer'
    
components:
  servers:
    barServer:  # <-- will be generated as `bar` (it's referred by the `bar` server)
      url: 'mqtt://localhost:1883'
      protocol: mqtt
    spamServer:  # <-- will NOT be generated (does not appear in the `servers` section)
      url: 'amqp://localhost:5672'
      protocol: amqp

In a similar way, only the channels from the channels section are considered for the server code generation. See the Channels for more details.

Server variables #

Server variables are used for the server URL templating. They are defined in the variables section of the server object and are substituted to the appropriate placeholders, enclosed in curly braces.

Server variables example
servers:
  myServer:
    url: 'kafka://{host}:{port}'
    protocol: kafka
    variables:
      host:
        default: 'localhost'
      port:
        default: '9092'

package servers

func MyServerURL(host string, port string) run.ParamString {
  paramMap := map[string]string{"host": host, "port": port}
  return run.ParamString{Expr: "kafka://{host}:{port}", ParamMap: paramMap}
}

// ...

ParamString complies the fmt.Stringer interface, so you can use it as a string:

fmt.Println(MyServerURL("localhost", "9092"))
// Output: kafka://localhost:9092

Server bindings #

Server bindings set the protocol-specific properties for the server. They are defined in the bindings section of the server object.

Server bindings example
servers:
  myServer:
    url: 'kafka://localhost:9092'
    protocol: kafka
    bindings:
      kafka:
        schemaRegistryUrl: 'http://localhost:8081'

package servers

//...

type MyServerBindings struct{}

func (m MyServerBindings) Kafka() kafka.ServerBindings {
  b := kafka.ServerBindings{SchemaRegistryURL: "http://localhost:8081"}
  return b
}

//...

Typically, bindings are passed to implementation to set Consumer or Producer creation options:

var consumer = implKafka.NewConsumer(MyServerURL().String(), MyServerBindings().Kafka(), nil)

x-go-name #

This extra field is used to explicitly set the name of the server in generated code. By default, the Go name is generated from the AsyncAPI server name.

Example
channels:
  myChannel:
    description: My channel

servers:
  myServer:
    url: 'kafka://localhost:9092'
    protocol: kafka
    x-go-name: FooBar


//...

type FooBar struct {
    producer kafka.Producer
    consumer kafka.Consumer
}

//...

x-ignore #

If this extra field is set to true, the server will not be generated. All references to this server in the generated code (if any) are replaced by Go any type.

Example
channels:
  myChannel:
    description: My channel

servers:
  myServer:
    url: 'kafka://localhost:9092'
    protocol: kafka
    x-ignore: true