asyncapi

package

v1.2.0 Latest Latest Go to latest Published: Aug 6, 2026 License: MIT Imports: 11 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/parnexcodes/swag-doc

Links

Open Source Insights

Documentation ¶

Overview ¶

Package asyncapi generates AsyncAPI 3.1.0 documents from captured WebSocket sessions.

Constants ¶

View Source

const AsyncAPIVersion = "3.1.0"

AsyncAPIVersion is the AsyncAPI specification version emitted by the generator.

Variables ¶

This section is empty.

Functions ¶

func Marshal ¶

func Marshal(doc *Document, format Format) ([]byte, error)

Marshal serializes the document in the requested format. YAML is produced by round-tripping the document through JSON, matching the OpenAPI generator's serialization contract.

Types ¶

type Channel ¶

type Channel struct {
	Address    string                      `json:"address,omitempty"`
	Messages   map[string]Ref              `json:"messages,omitempty"`
	Parameters map[string]ChannelParameter `json:"parameters,omitempty"`
}

Channel describes one WebSocket endpoint: an addressable component with the messages that can be exchanged on it.

type ChannelParameter ¶

type ChannelParameter struct {
	Schema map[string]any `json:"schema"`
}

ChannelParameter describes a path parameter of a channel address.

type Components ¶

type Components struct {
	Schemas         map[string]map[string]any `json:"schemas,omitempty"`
	Messages        map[string]Message        `json:"messages,omitempty"`
	SecuritySchemes map[string]SecurityScheme `json:"securitySchemes,omitempty"`
}

Components holds reusable schemas, messages, and security schemes.

type Config ¶

type Config struct {
	Title       string
	Description string
	Version     string
	BasePath    string
}

Config configures the AsyncAPI generator.

type Document ¶

type Document struct {
	AsyncAPI   string               `json:"asyncapi"`
	Info       Info                 `json:"info"`
	Servers    map[string]Server    `json:"servers,omitempty"`
	Channels   map[string]Channel   `json:"channels"`
	Operations map[string]Operation `json:"operations"`
	Components Components           `json:"components,omitempty"`
}

Document is an AsyncAPI 3.1.0 document. The JSON tags are the source of truth for both JSON and YAML serialization.

The 3.x model separates channels (addressable components) from operations (what the documented application does): channels declare the messages exchanged on an address, and a top-level operations map references them with an action of "send" or "receive".

type Format ¶

type Format string

Format identifies a serialization format for generated documents.

const (
	// FormatJSON serializes the document as indented JSON. It is the default.
	FormatJSON Format = "json"
	// FormatYAML serializes the document as YAML.
	FormatYAML Format = "yaml"
)

type Generator ¶

type Generator struct {
	// contains filtered or unexported fields
}

Generator generates AsyncAPI documents from captured WebSocket sessions.

func NewGenerator ¶

func NewGenerator(config Config) *Generator

NewGenerator creates a generator with the given configuration.

func (*Generator) AddSession ¶

func (g *Generator) AddSession(session proxy.WebSocketSession)

AddSession adds a captured WebSocket session to be analyzed.

func (*Generator) Generate ¶

func (g *Generator) Generate() (*Document, error)

Generate produces an AsyncAPI document from the collected sessions.

func (*Generator) LoadWebSocketSessionsFromDirectory ¶

func (g *Generator) LoadWebSocketSessionsFromDirectory(dirPath string) error

LoadWebSocketSessionsFromDirectory loads sessions from all ws-session-*.json files in a directory. HTTP session files are ignored.

func (*Generator) LoadWebSocketSessionsFromFile ¶

func (g *Generator) LoadWebSocketSessionsFromFile(filename string) error

LoadWebSocketSessionsFromFile loads sessions from a ws-session JSON file (either an array of sessions or a single session object).

type Info ¶

type Info struct {
	Title       string `json:"title"`
	Version     string `json:"version"`
	Description string `json:"description,omitempty"`
}

Info carries document metadata.

type Message ¶

type Message struct {
	Name        string         `json:"name"`
	ContentType string         `json:"contentType,omitempty"`
	Payload     map[string]any `json:"payload"`
}

Message describes one message type exchanged on a channel.

type Operation ¶

type Operation struct {
	Action   string `json:"action"`
	Channel  Ref    `json:"channel"`
	Messages []Ref  `json:"messages,omitempty"`
	Security []Ref  `json:"security,omitempty"`
}

Operation is an operation the documented application MUST implement. Action is "send" (the application sends to the channel) or "receive" (the application receives from the channel).

type Ref ¶

type Ref struct {
	Ref string `json:"$ref"`
}

Ref is a $ref pointer object.

type SecurityScheme ¶

type SecurityScheme struct {
	Type         string `json:"type"`
	Scheme       string `json:"scheme,omitempty"`
	BearerFormat string `json:"bearerFormat,omitempty"`
	In           string `json:"in,omitempty"`
	Name         string `json:"name,omitempty"`
}

SecurityScheme is an AsyncAPI security scheme.

type Server ¶

type Server struct {
	URL             string `json:"url"`
	Protocol        string `json:"protocol"`
	ProtocolVersion string `json:"protocolVersion,omitempty"`
}

Server describes a WebSocket server endpoint.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL