AsyncAPI Generator for Go

https://github.com/swaggest/go-asyncapi
Admin
This library helps to create AsyncAPI specifications from Go message structures, supporting various...
Tokens:8,404
Snippets:22
Trust Score:8.1
License:MIT
Update:11 months ago
Show doc for...
Tokens:
Raw
### Generate AsyncAPI 2.4.0 spec from Go structs

Source: https://github.com/swaggest/go-asyncapi/blob/master/README.md

Demonstrates generating AsyncAPI 2.4.0 specifications from Go struct definitions using the swaggest/go-asyncapi reflector. Shows message schema creation with field tags, server configuration with AMQP protocol, channel setup with publish/subscribe operations, and YAML output generation. The example includes two message types with nested structures and various AsyncAPI-specific bindings.

```go
package asyncapi_test

import (
	"fmt"
	"os"
	"time"

	"github.com/swaggest/go-asyncapi/reflector/asyncapi-2.4.0"
	"github.com/swaggest/go-asyncapi/spec-2.4.0"
)

func main() {
	type SubItem struct {
		Key    string  `json:\"key\" description:\"Item key\"`
		Values []int64 `json:\"values\" uniqueItems:\"true\" description:\"List of item values\"`
	}

	type MyMessage struct {
		Name      string    `path:\"name\" description:\"Name\"`
		CreatedAt time.Time `json:\"createdAt\" description:\"Creation time\"`
		Items     []SubItem `json:\"items\" description:\"List of items\"`
	}

	type MyAnotherMessage struct {
		TraceID string  `header:\"X-Trace-ID\" description:\"Tracing header\" required:\"true\"`
		Item    SubItem `json:\"item\" description:\"Some item\"`
	}

	asyncAPI := spec.AsyncAPI{}
	asyncAPI.Info.Version = \"1.2.3\"
	asyncAPI.Info.Title = \"My Lovely Messaging API\"

	asyncAPI.AddServer(\"live\", spec.Server{
		URL:             \"api.{country}.lovely.com:5672\",
		Description:     \"Production instance.\",
		ProtocolVersion: \"0.9.1\",
		Protocol:        \"amqp\",
		Variables: map[string]spec.ServerVariable{
			\"country\": {
				Enum:        []string{\"RU\", \"US\", \"DE\", \"FR\"},
				Default:     \"US\",
				Description: \"Country code.\",
			},
		},
	})

	reflector := asyncapi.Reflector{}
	reflector.Schema = &asyncAPI

	mustNotFail := func(err error) {
		if err != nil {
			panic(err.Error())
		}
	}

	mustNotFail(reflector.AddChannel(asyncapi.ChannelInfo{
		Name: \"one.{name}.two\",
	
```

--------------------------------

### Add AsyncAPI Server with URL Variables

Source: https://context7.com/swaggest/go-asyncapi/llms.txt

Configures server connection details including URL templates with variables for multi-environment deployments. Supports protocol specifications, security requirements, and protocol-specific bindings. Uses URL variable substitution for regional deployment configurations.

```Go
package main

import (
	"fmt"

	asyncapi "github.com/swaggest/go-asyncapi/reflector/asyncapi-2.4.0"
	"github.com/swaggest/go-asyncapi/spec-2.4.0"
)

type PaymentEvent struct {
	TransactionID string  `json:"transactionId" description:"Transaction identifier"`
	Amount        float64 `json:"amount" description:"Payment amount"`
	Currency      string  `json:"currency" description:"Currency code (USD, EUR, GBP)"`
}

func main() {
	asyncAPI := spec.AsyncAPI{}
	asyncAPI.Info.Title = "Payment Gateway API"
	asyncAPI.Info.Version = "3.0.0"
	asyncAPI.Info.Description = "Real-time payment processing events"
	asyncAPI.Info.Contact = &spec.Contact{
		Name:  "Platform Team",
		Email: "platform@example.com",
		URL:   "https://example.com/support",
	}

	// Add server with URL variables for multi-region deployment
	asyncAPI.AddServer("payments-broker", spec.Server{
		URL:             "{protocol}://{region}.payments.example.com:{port}",
		Protocol:        "amqps",
		ProtocolVersion: "0.9.1",
		Description:     "Regional payment processing brokers with TLS",
		Variables: map[string]spec.ServerVariable{
			"protocol": {
				Enum:        []string{"amqps"},
				Default:     "amqps",
				Description: "Secure AMQP protocol",
			},
			"region": {
				Enum:        []string{"us-east", "us-west", "eu-central", "ap-southeast"},
				Default:     "us-east",
				Description: "Geographic region for data residency",
			},
			"port": {
				Enum:        []string{"5671"},
				Default:     "5671",
				Description: "TLS-enabled AMQP port",
			},
		},
	})

	// Add development server
	asyncAPI.AddServer("local-dev", spec.Server{
		URL:             "localhost:5672",
		Protocol:        "amqp",
		ProtocolVersion: "0.9.1",
		Description:     "Local development broker (no TLS)",
	})

	reflector := asyncapi.Reflector{Schema: &asyncAPI}

	err := reflector.AddChannel(asyncapi.ChannelInfo{
		Name: "payments.processed",
		Publish: &asyncapi.MessageSample{
			MessageEntity: spec.MessageEntity{
				Summary: "Payment processed notification",
			},
			MessageSample: new(PaymentEvent),
		},
	})
	if err != nil {
		panic(err)
	}

	yaml, err := reflector.Schema.MarshalYAML()
	if err != nil {
		panic(err)
	}

	fmt.Println(string(yaml))

	// Output includes:
	// - Two server definitions (production and development)
	// - URL template with protocol, region, and port variables
	// - Enum constraints for each variable
	// - Default values for variable substitution
}
```

--------------------------------

### Add message channels with automatic schema generation using Go

Source: https://context7.com/swaggest/go-asyncapi/llms.txt

The example shows how to initialize an AsyncAPI document, configure an AMQP server, and add both publish and subscribe channels by reflecting Go structs. It depends on the go-asyncapi package and the spec‑2.4.0 module. The generated YAML includes channel definitions, message schemas, and header specifications.

```Go
package main

import (
	"fmt"
	"time"

	asyncapi "github.com/swaggest/go-asyncapi/reflector/asyncapi-2.4.0"
	"github.com/swaggest/go-asyncapi/spec-2.4.0"
)

type UserCreatedEvent struct {
	UserID    string    `path:"userId" description:"User identifier"`
	Username  string    `json:"username" description:"Username"`
	Email     string    `json:"email" description:"Email address"`
	CreatedAt time.Time `json:"createdAt" description:"Account creation timestamp"`
}

type NotificationMessage struct {
	TraceID   string `header:"X-Trace-ID" description:"Distributed trace ID" required:"true"`
	MessageID string `json:"messageId" description:"Unique message identifier"`
	Content   string `json:"content" description:"Notification content"`
	Priority  int    `json:"priority" description:"Message priority (1-5)"`
}

func main() {
	// Initialize AsyncAPI document
	asyncAPI := spec.AsyncAPI{}
	asyncAPI.Info.Title = "User Service API"
	asyncAPI.Info.Version = "1.0.0"
	asyncAPI.Info.Description = "Event-driven API for user management"

	// Add AMQP server configuration
	asyncAPI.AddServer("production", spec.Server{
		URL:              "amqp.example.com:5672",
		Protocol:         "amqp",
		ProtocolVersion:  "0.9.1",
		Description:      "Production AMQP broker",
	})

	reflector := asyncapi.Reflector{Schema: &asyncAPI}

	// Add channel with publish operation and path parameter
	err := reflector.AddChannel(asyncapi.ChannelInfo{
		Name: "user.{userId}.created",
		Publish: &asyncapi.MessageSample{
			MessageEntity: spec.MessageEntity{
				Summary:     "User created event",
				Description: "Published when a new user account is created",
				ContentType: "application/json",
			},
			MessageSample: new(UserCreatedEvent),
		},
	})
	if err != nil {
		panic(err)
	}

	// Add channel with subscribe operation and headers
	err = reflector.AddChannel(asyncapi.ChannelInfo{
		Name: "notifications",
		Subscribe: &asyncapi.MessageSample{
			MessageEntity: spec.MessageEntity{
				Summary:     "Notification consumer",
				Description: "Receives notification messages for processing",
			},
			MessageSample: new(NotificationMessage),
		},
	})
	if err != nil {
		panic(err)
	}

	// Export to YAML
	yaml, err := reflector.Schema.MarshalYAML()
	if err != nil {
		panic(err)
	}

	fmt.Println(string(yaml))

	// Output includes:
	// - asyncapi: 2.4.0
	// - Channel "user.{userId}.created" with userId path parameter
	// - Publish operation with UserCreatedEvent schema
	// - Channel "notifications" with subscribe operation
	// - Message headers schema with required X-Trace-ID
	// - Component schemas for both message types with descriptions
}
```

--------------------------------

### Example of payload for publish channel

Source: https://github.com/swaggest/go-asyncapi/blob/master/reflector/asyncapi-2.0.0/sample.md

This snippet shows an example of payload for the publish channel 'one.{name}.two'. It includes a creation time and a list of items, each with a key and a list of values.

```json
{
  "createdAt": "2020-04-25T11:17:53Z",
  "items": [
    {
      "key": "string",
      "values": [
        0
      ]
    }
  ]
}
```

--------------------------------

### Example of headers for subscribe channel

Source: https://github.com/swaggest/go-asyncapi/blob/master/reflector/asyncapi-2.0.0/sample.md

This snippet shows an example of headers for the subscribe channel 'another.one'. It includes a tracing header 'X-Trace-ID' which can be any string value.

```json
{
  "X-Trace-ID": "string"
}
```

--------------------------------

### Example of payload for subscribe channel

Source: https://github.com/swaggest/go-asyncapi/blob/master/reflector/asyncapi-2.0.0/sample.md

This snippet shows an example of payload for the subscribe channel 'another.one'. It includes an item object with a key and a list of values.

```json
{
  "item": {
    "key": "string",
    "values": [
      0
    ]
  }
}
```

--------------------------------

### Support Multiple AsyncAPI Versions in Go

Source: https://context7.com/swaggest/go-asyncapi/llms.txt

This Go code demonstrates how to generate AsyncAPI specifications for different versions (2.4.0 and 2.1.0) using the go-asyncapi library. It shows how to import specific version packages and construct specifications compatible with older or newer tooling. This is crucial for maintaining compatibility across different environments.

```go
package main

import (
	"fmt"

	// AsyncAPI 2.4.0 (latest, recommended)
	asyncapi240 "github.com/swaggest/go-asyncapi/reflector/asyncapi-2.4.0"
	spec240 "github.com/swaggest/go-asyncapi/spec-2.4.0"

	// AsyncAPI 2.1.0 (for older tooling compatibility)
	asyncapi210 "github.com/swaggest/go-asyncapi/reflector/asyncapi-2.1.0"
	spec210 "github.com/swaggest/go-asyncapi/spec-2.1.0"
)

type Message struct {
	ID   string `json:"id" description:"Message ID"`
	Text string `json:"text" description:"Message text"`
}

func main() {
	// Generate AsyncAPI 2.4.0 spec (latest features)
	asyncAPI240 := spec240.AsyncAPI{}
	asyncAPI240.Info.Title = "My API v2.4.0"
	asyncAPI240.Info.Version = "1.0.0"
	asyncAPI240.AddServer("server", spec240.Server{
		URL:      "example.com",
		Protocol: "mqtt",
	})

	reflector240 := asyncapi240.Reflector{Schema: &asyncAPI240}
	err := reflector240.AddChannel(asyncapi240.ChannelInfo{
		Name: "messages",
		Publish: &asyncapi240.MessageSample{
			MessageEntity: spec240.MessageEntity{
				Summary: "Message event v2.4.0",
			},
			MessageSample: new(Message),
		},
	})
	if err != nil {
		panic(err)
	}

	yaml240, _ := reflector240.Schema.MarshalYAML()
	fmt.Println("AsyncAPI 2.4.0:")
	fmt.Println(string(yaml240))

	// Generate AsyncAPI 2.1.0 spec (for older tooling)
	asyncAPI210 := spec210.AsyncAPI{}
	asyncAPI210.Info.Title = "My API v2.1.0"
	asyncAPI210.Info.Version = "1.0.0"
	asyncAPI210.AddServer("server", spec210.Server{
		URL:      "example.com",
		Protocol: "mqtt",
	})

	reflector210 := asyncapi210.Reflector{Schema: &asyncAPI210}
	err = reflector210.AddChannel(asyncapi210.ChannelInfo{
		Name: "messages",
		Publish: &asyncapi210.MessageSample{
			MessageEntity: spec210.MessageEntity{
				Summary: "Message event v2.1.0",
			},
			MessageSample: new(Message),
		},
	})
	if err != nil {
		panic(err)
	}

	yaml210, _ := reflector210.Schema.MarshalYAML()
	fmt.Println("\nAsyncAPI 2.1.0:")
	fmt.Println(string(yaml210))

	// Version differences:
	// - 2.4.0 adds support for message traits and operation traits
	// - 2.1.0 added support for message examples
	// - 2.0.0 is the foundational spec version
	// - Choose version based on tooling compatibility requirements
}

```

--------------------------------

### Configure Kafka Producer and Consumer Bindings in Go

Source: https://context7.com/swaggest/go-asyncapi/llms.txt

This Go code configures Kafka bindings for an AsyncAPI specification using the go-asyncapi library. It demonstrates setting up a Kafka producer with a message key and a Kafka consumer with a specific group ID. The code defines event structures, adds Kafka servers, and then uses a reflector to add channels with detailed Kafka operation and message bindings. The resulting AsyncAPI specification in YAML format is then printed to the console.

```go
package main

import (
	"fmt"
	"time"

	asyncapi "github.com/swaggest/go-asyncapi/reflector/asyncapi-2.4.0"
	"github.com/swaggest/go-asyncapi/spec-2.4.0"
)

type LogEvent struct {
	Timestamp time.Time              `json:"timestamp" description:"Event timestamp"
	Level     string                 `json:"level" description:"Log level (INFO, WARN, ERROR)"
	Service   string                 `json:"service" description:"Service name"
	Message   string                 `json:"message" description:"Log message"
	Metadata  map[string]interface{} `json:"metadata" description:"Additional context"
}

type MetricEvent struct {
	MetricName string  `json:"metricName" description:"Metric identifier"
	Value      float64 `json:"value" description:"Metric value"
	Tags       []string `json:"tags" description:"Metric tags"
}

func main() {
	asyncAPI := spec.AsyncAPI{}
	asyncAPI.Info.Title = "Observability Platform API"
	asyncAPI.Info.Version = "2.0.0"

	asyncAPI.AddServer("kafka-cluster", spec.Server{
		URL:             "kafka.example.com:9092",
		Protocol:        "kafka",
		ProtocolVersion: "2.8.0",
		Description:     "Production Kafka cluster",
	})

	reflector := asyncapi.Reflector{Schema: &asyncAPI}

	// Configure Kafka producer with message key
	err := reflector.AddChannel(asyncapi.ChannelInfo{
		Name: "logs-topic",
		BaseOperation: &spec.Operation{
			Bindings: &spec.OperationBindingsObject{
				Kafka: &spec.KafkaOperation{
					GroupID:  (&spec.KafkaOperationGroupID{}).WithStringProperty("log-processors"),
					ClientID: (&spec.KafkaOperationClientID{}).WithStringProperty("observability-service"),
				},
			},
		},
		Publish: &asyncapi.MessageSample{
			MessageEntity: spec.MessageEntity{
				Summary:     "Log event producer",
				Description: "Publishes application logs to Kafka",
				Bindings: &spec.MessageBindingsObject{
					Kafka: &spec.KafkaMessage{
						Key: (&spec.KafkaMessageKey{}).WithStringProperty("service-name"),
					},
				},
			},
			MessageSample: new(LogEvent),
		},
	})
	if err != nil {
		panic(err)
	}

	// Configure Kafka consumer with different group ID
	err = reflector.AddChannel(asyncapi.ChannelInfo{
		Name: "metrics-topic",
		BaseOperation: &spec.Operation{
			Bindings: &spec.OperationBindingsObject{
				Kafka: &spec.KafkaOperation{
					GroupID:  (&spec.KafkaOperationGroupID{}).WithStringProperty("metric-aggregators"),
					ClientID: (&spec.KafkaOperationClientID{}).WithStringProperty("analytics-service"),
				},
			},
		},
		Subscribe: &asyncapi.MessageSample{
			MessageEntity: spec.MessageEntity{
				Summary:     "Metric event consumer",
				Description: "Consumes and aggregates metric events",
			},
			MessageSample: new(MetricEvent),
		},
	})
	if err != nil {
		panic(err)
	}

	yaml, err := reflector.Schema.MarshalYAML()
	if err != nil {
		panic(err)
	}

	fmt.Println(string(yaml))

	// Output includes Kafka bindings with:
	// - Consumer group IDs for both operations
	// - Client IDs for service identification
	// - Message key configuration for partitioning
	// - Binding version 0.3.0 for Kafka spec compliance
}

```

--------------------------------

### Configure AMQP Channel Bindings in Go

Source: https://context7.com/swaggest/go-asyncapi/llms.txt

This Go code snippet demonstrates how to configure AMQP channel bindings using the go-asyncapi library. It sets up an AsyncAPI schema, defines a server for RabbitMQ, and adds a channel with specific AMQP exchange and queue configurations, including routing key information. The output is the generated AsyncAPI schema in YAML format.

```go
package main

import (
	"fmt"

	asyncapi "github.com/swaggest/go-asyncapi/reflector/asyncapi-2.4.0"
	"github.com/swaggest/go-asyncapi/spec-2.4.0"
)

type OrderEvent struct {
	OrderID   string  `path:"orderId" description:"Order identifier"`
	ProductID string  `json:"productId" description:"Product SKU"`
	Quantity  int     `json:"quantity" description:"Order quantity"`
	Total     float64 `json:"total" description:"Order total amount"`
}

func main() {
	asyncAPI := spec.AsyncAPI{}
	asyncAPI.Info.Title = "Order Processing API"
	asyncAPI.Info.Version = "1.0.0"

	asyncAPI.AddServer("rabbitmq", spec.Server{
		URL:             "rabbitmq.{environment}.example.com:5672",
		Protocol:        "amqp",
		ProtocolVersion: "0.9.1",
		Variables: map[string]spec.ServerVariable{
			"environment": {
				Enum:        []string{"dev", "staging", "prod"},
				Default:     "prod",
				Description: "Deployment environment",
			},
		},
	})

	reflector := asyncapi.Reflector{Schema: &asyncAPI}

	// Configure AMQP channel with exchange and routing key
	err := reflector.AddChannel(asyncapi.ChannelInfo{
		Name: "orders.{orderId}.placed",
		BaseChannelItem: &spec.ChannelItem{
			Description: "Order placement events routed by order ID",
			Bindings: &spec.ChannelBindingsObject{
				Amqp: &spec.AmqpChannel{
					Is: spec.AmqpChannelIsRoutingKey,
					Exchange: &spec.AmqpChannelExchange{
						Name:       "orders-exchange",
						Type:       "topic",
						Durable:    true,
						AutoDelete: false,
					},
					Queue: &spec.AmqpChannelQueue{
						Name:       "orders-queue",
						Durable:    true,
						Exclusive:  false,
						AutoDelete: false,
					},
				},
			},
		},
		Publish: &asyncapi.MessageSample{
			MessageEntity: spec.MessageEntity{
				Summary:     "Order placed event",
				Description: "Published when customer places an order",
			},
			MessageSample: new(OrderEvent),
		},
	})
	if err != nil {
		panic(err)
	}

	yaml, err := reflector.Schema.MarshalYAML()
	if err != nil {
		panic(err)
	}

	fmt.Println(string(yaml))

	// Output includes AMQP bindings with:
	// - Exchange configuration (name, type, durability)
	// - Queue settings (durable, non-exclusive)
	// - Routing key channel type
	// - Order schema with path parameter
}

```

--------------------------------

### Export AsyncAPI Spec to YAML and JSON in Go

Source: https://context7.com/swaggest/go-asyncapi/llms.txt

This Go code snippet demonstrates how to build an AsyncAPI document using the go-asyncapi library and then export it to both YAML and JSON formats. It includes defining a simple event structure, adding a channel, and writing the generated specification to files. The output can be used with AsyncAPI tooling for validation and documentation generation.

```go
package main

import (
	"encoding/json"
	"fmt"
	"os"

	asyncapi "github.com/swaggest/go-asyncapi/reflector/asyncapi-2.4.0"
	spec "github.com/swaggest/go-asyncapi/spec-2.4.0"
)

type SimpleEvent struct {
	ID      string `json:"id" description:"Event identifier"`
	Message string `json:"message" description:"Event message"`
}

func main() {
	// Build AsyncAPI document
	asyncAPI := spec.AsyncAPI{}
	asyncAPI.Info.Title = "Export Example API"
	asyncAPI.Info.Version = "1.0.0"
	asyncAPI.Info.Description = "Demonstrates YAML and JSON export"
	asyncAPI.DefaultContentType = "application/json"

	asyncAPI.AddServer("default", spec.Server{
		URL:      "messaging.example.com",
		Protocol: "amqp",
	})

	reflector := asyncapi.Reflector{Schema: &asyncAPI}

	err := reflector.AddChannel(asyncapi.ChannelInfo{
		Name: "events",
		Publish: &asyncapi.MessageSample{
			MessageEntity: spec.MessageEntity{
				Summary: "Simple event message",
			},
			MessageSample: new(SimpleEvent),
		},
	})
	if err != nil {
		panic(err)
	}

	// Export to YAML (recommended format)
	yamlBytes, err := reflector.Schema.MarshalYAML()
	if err != nil {
		panic(err)
	}

	err = os.WriteFile("asyncapi.yaml", yamlBytes, 0644)
	if err != nil {
		panic(err)
	}
	fmt.Println("Exported to asyncapi.yaml")
	fmt.Println(string(yamlBytes))

	// Export to JSON
	jsonBytes, err := json.MarshalIndent(reflector.Schema, "", "  ")
	if err != nil {
		panic(err)
	}

	err = os.WriteFile("asyncapi.json", jsonBytes, 0644)
	if err != nil {
		panic(err)
	}
	fmt.Println("\nExported to asyncapi.json")
	fmt.Println(string(jsonBytes))

	// Validate the specification complies with AsyncAPI standard
	// Use external tools:
	// - npm install -g @asyncapi/cli
	// - asyncapi validate asyncapi.yaml
	// - asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o ./docs

	fmt.Println("\nExport complete. Use AsyncAPI CLI to:")
	fmt.Println("  asyncapi validate asyncapi.yaml")
	fmt.Println("  asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template")
}

```

--------------------------------

### Reflector.AddChannel - Add message channel with automatic schema generation

Source: https://context7.com/swaggest/go-asyncapi/llms.txt

The primary method for adding message channels to an AsyncAPI specification. It accepts channel configuration with optional publish/subscribe operations, automatically generates JSON schemas from Go struct samples, extracts path parameters and headers from struct tags, and registers reusable component definitions.

```APIDOC
## POST /channels

### Description
Adds a message channel to the AsyncAPI specification. This method automatically generates JSON schemas from provided Go struct samples, extracts channel parameters and message headers from Go struct tags, and registers reusable component definitions.

### Method
POST

### Endpoint
/channels

### Parameters
#### Request Body
- **Name** (string) - Required - The name of the channel, potentially including parameters like `user.{userId}.created`.
- **Publish** (object) - Optional - Configuration for a publish operation.
  - **MessageEntity** (object) - Required - Details about the message being published.
    - **Summary** (string) - Optional - A short summary of the message.
    - **Description** (string) - Optional - A detailed description of the message.
    - **ContentType** (string) - Optional - The content type of the message (e.g., `application/json`).
  - **MessageSample** (object) - Required - A sample Go struct representing the message payload.
- **Subscribe** (object) - Optional - Configuration for a subscribe operation.
  - **MessageEntity** (object) - Required - Details about the message being subscribed to.
    - **Summary** (string) - Optional - A short summary of the message.
    - **Description** (string) - Optional - A detailed description of the message.
  - **MessageSample** (object) - Required - A sample Go struct representing the message payload.

### Request Example
```json
{
  "Name": "user.{userId}.created",
  "Publish": {
    "MessageEntity": {
      "Summary": "User created event",
      "Description": "Published when a new user account is created",
      "ContentType": "application/json"
    },
    "MessageSample": {
      "UserID": "string",
      "Username": "string",
      "Email": "string",
      "CreatedAt": "time.Time"
    }
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the channel was added successfully.

#### Response Example
```json
{
  "message": "Channel 'user.{userId}.created' added successfully."
}
```
```

--------------------------------

### Go AsyncAPI Schema Generation with Struct Tags

Source: https://context7.com/swaggest/go-asyncapi/llms.txt

This Go code demonstrates how to use struct tags to define an AsyncAPI schema. It maps Go struct fields to channel parameters, message headers, and payload fields, applying constraints like 'required', 'format', 'uniqueItems', 'minimum', 'maximum', and 'enum'. The generated schema is then printed as YAML.

```go
package main

import (
	"fmt"
	"time"

	asyncapi "github.com/swaggest/go-asyncapi/reflector/asyncapi-2.4.0"
	"github.com/swaggest/go-asyncapi/spec-2.4.0"
)

// Demonstrates all supported struct tags
type CompleteMessageExample struct {
	// Path parameters - extracted to channel parameters
	ResourceID string `path:"resourceId" description:"Resource identifier in channel path"`
	TenantID   string `path:"tenantId" description:"Multi-tenant identifier"`

	// Headers - extracted to message headers schema
	CorrelationID string `header:"X-Correlation-ID" description:"Request correlation ID" required:"true"`
	RequestID     string `header:"X-Request-ID" description:"Unique request identifier"`

	// Payload fields - standard JSON schema tags
	EventType string    `json:"eventType" description:"Event type identifier" required:"true"`
	Timestamp time.Time `json:"timestamp" description:"Event timestamp" format:"date-time"`
	Data      EventData `json:"data" description:"Event payload data"`

	// Array with validation
	Tags []string `json:"tags" description:"Event tags" uniqueItems:"true"`

	// Numeric constraints
	Priority int `json:"priority" description:"Priority level" minimum:"1" maximum:"10"`

	// Optional field (pointer indicates nullable)
	Metadata *map[string]interface{} `json:"metadata,omitempty" description:"Additional metadata"`
}

type EventData struct {
	Action   string   `json:"action" description:"Action performed" enum:"create,update,delete"`
	Resource string `json:"resource" description:"Resource type"`
	Changes  []string `json:"changes" description:"List of changed fields"`
}

func main() {
	asyncAPI := spec.AsyncAPI{}
	asyncAPI.Info.Title = "Complete Tag Example API"
	asyncAPI.Info.Version = "1.0.0"

	asyncAPI.AddServer("demo", spec.Server{
		URL:      "demo.example.com",
		Protocol: "amqp",
	})

	reflector := asyncapi.Reflector{Schema: &asyncAPI}

	err := reflector.AddChannel(asyncapi.ChannelInfo{
		Name: "tenants.{tenantId}.resources.{resourceId}.events",
		Publish: &asyncapi.MessageSample{
			MessageEntity: spec.MessageEntity{
				Summary:     "Resource event with complete tag examples",
				Description: "Demonstrates all supported struct tag features",
			},
			MessageSample: new(CompleteMessageExample),
		},
	})
	if err != nil {
		panic(err)
	}

	yaml, err := reflector.Schema.MarshalYAML()
	if err != nil {
		panic(err)
	}

	fmt.Println(string(yaml))

	// Generated schema includes:
	// - Channel path parameters: tenantId and resourceId
	// - Message headers: X-Correlation-ID (required) and X-Request-ID
	// - Payload schema with all fields and their constraints:
	//   * eventType as required string
	//   * timestamp with date-time format
	//   * tags array with uniqueItems constraint
	//   * priority with min/max validation
	//   * action enum with allowed values
	// - Nested EventData schema as component
	// - Nullable metadata field (array or null type)
}

```

--------------------------------

### PUBLISH one.{name}.two

Source: https://github.com/swaggest/go-asyncapi/blob/master/reflector/asyncapi-2.0.0/sample.md

Enables publishers to send messages to the `one.{name}.two` channel, where `{name}` is a required path parameter. The payload contains creation time and a list of items.

```APIDOC
## PUBLISH one.{name}.two\n\n### Description\nEnables publishers to send messages to the `one.{name}.two` channel, where `{name}` is a required path parameter. The payload contains creation time and a list of items.\n\n### Method\nPUBLISH\n\n### Endpoint\none.{name}.two\n\n### Parameters\n#### Path Parameters\n- **name** (string) - Required - Name\n\n#### Query Parameters\n*(none)*\n\n#### Request Body\n- **createdAt** (string) - Required - Creation time\n- **items** (array[object]) - Required - List of items\n  - **items.key** (string) - Required - Item key\n  - **items.values** (array[integer - Required - List of item values\n\n### Request Example\n{\n  "createdAt": "2020-04-25T11:17:53Z",\n  "items": [\n    {\n      "key": "string",\n      "values": [\n        0\n      ]\n    }\n  ]\n}\n\n### Response\nNone (publish operation does not return a response).\n\n### Response Example\nN/A
```

--------------------------------

### SUBSCRIBE.one

Source: https://github.com/swaggest/go-asyncapi/blob/master/reflector/asyncapi-2.0.0/sample.md

Allows consumers to receive messages from the `another.one` channel. Includes a tracing header and an `item` payload with key and values.

```APIDOC
## SUBSCRIBE another.one\n\n### Description\nAllows consumers to receive messages from the `another.one` channel. Includes a tracing header and an `item` payload with key and values.\n\n### Method\nSUBSCRIBE\n\n### Endpoint\nanother.one\n\n### Parameters\n#### Path Parameters\n*(none)*\n\n#### Query Parameters\n*(none)*\n\n#### Request Body\n-item** (object) - Required - Some item\n- **item.key** (string) - Required - Item key\n- **item.values** (array[integer]) - Required - List of item values\n\n### Request Example\n{\n  "item": {\n    "key": "string",\n    "values": [\n      0\n    ]\n  }\n}\n\n### Response\nNone (messages are pushed to the subscriber).\n\n### Response Example\nN/A
```
Tokens:
Raw