AsyncAPI Generation

Generate AsyncAPI 3.0 specifications from your contracts for documentation and tooling.

Installation

pnpm add @amqp-contract/asyncapi

Basic Usage

import { AsyncAPIGenerator } from "@amqp-contract/asyncapi";
import { ZodToJsonSchemaConverter } from "@orpc/zod/zod4";
import { contract } from "./contract";

const generator = new AsyncAPIGenerator({
  schemaConverters: [new ZodToJsonSchemaConverter()],
});

const spec = await generator.generate(contract, {
  info: {
    title: "Order Processing API",
    version: "1.0.0",
    description: "Type-safe AMQP messaging for order processing",
  },
  servers: {
    production: {
      host: "rabbitmq.example.com:5671",
      protocol: "amqps",
      description: "Production server (TLS)",
    },
    development: {
      host: "localhost:5672",
      protocol: "amqp",
      description: "Local development",
    },
  },
});

console.log(JSON.stringify(spec, null, 2));

Generated Specification

The specification includes:

• Channels - Exchanges and queues
• Operations - Send (publish) and receive (consume)
• Messages - Schemas automatically converted to JSON Schema
• Bindings - AMQP-specific routing configuration

Configuration

Server Configuration

Define multiple servers:

const generator = new AsyncAPIGenerator({
  schemaConverters: [new ZodToJsonSchemaConverter()],
});

const spec = await generator.generate(contract, {
  info: { title: "My API", version: "1.0.0" },
  servers: {
    production: {
      host: "prod.rabbitmq.com:5672",
      protocol: "amqp",
      description: "Production server",
    },
    staging: {
      host: "staging.rabbitmq.com:5672",
      protocol: "amqp",
      description: "Staging server",
    },
  },
});

API Information

Add metadata:

const generator = new AsyncAPIGenerator({
  schemaConverters: [new ZodToJsonSchemaConverter()],
});

const spec = await generator.generate(contract, {
  info: {
    title: 'Order Processing API',
    version: '1.0.0',
    description: 'Order processing system',
    contact: {
      name: 'API Support',
      email: 'support@example.com',
    },
    license: {
      name: 'MIT',
      url: 'https://opensource.org/licenses/MIT',
    },
  },
  servers: { ... },
});

Exporting Specifications

JSON Export

import { AsyncAPIGenerator } from '@amqp-contract/asyncapi';
import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4';
import { writeFileSync } from 'fs';

const generator = new AsyncAPIGenerator({
  schemaConverters: [new ZodToJsonSchemaConverter()],
});

const spec = await generator.generate(contract, { ... });
writeFileSync('asyncapi.json', JSON.stringify(spec, null, 2));

YAML Export

import { AsyncAPIGenerator } from '@amqp-contract/asyncapi';
import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4';
import { writeFileSync } from 'fs';
import YAML from 'yaml';

const generator = new AsyncAPIGenerator({
  schemaConverters: [new ZodToJsonSchemaConverter()],
});

const spec = await generator.generate(contract, { ... });
writeFileSync('asyncapi.yaml', YAML.stringify(spec));

Using Generated Specs

AsyncAPI Studio

Visualize your API at AsyncAPI Studio:

1. Generate your specification
2. Copy JSON or YAML
3. Paste into AsyncAPI Studio
4. View interactive documentation

AsyncAPI CLI

Generate documentation and code:

# Install
npm install -g @asyncapi/cli

# Generate HTML docs
asyncapi generate fromFile asyncapi.json @asyncapi/html-template -o docs/

# Validate spec
asyncapi validate asyncapi.json

Complete Example

import { AsyncAPIGenerator } from "@amqp-contract/asyncapi";
import { ZodToJsonSchemaConverter } from "@orpc/zod/zod4";
import { writeFileSync } from "fs";
import YAML from "yaml";

import { contract } from "./contract";

const generator = new AsyncAPIGenerator({
  schemaConverters: [new ZodToJsonSchemaConverter()],
});

const spec = await generator.generate(contract, {
  info: {
    title: "Order Processing API",
    version: "1.0.0",
    description: "Type-safe AMQP messaging",
    contact: {
      name: "API Team",
      email: "api@example.com",
    },
  },
  servers: {
    production: {
      host: "prod.rabbitmq.com:5672",
      protocol: "amqp",
      description: "Production server",
    },
  },
});

// Export
writeFileSync("asyncapi.json", JSON.stringify(spec, null, 2));
writeFileSync("asyncapi.yaml", YAML.stringify(spec));

console.log("✅ Generated AsyncAPI specs");
console.log("   Channels:", Object.keys(spec.channels).length);
console.log("   Operations:", Object.keys(spec.operations).length);

Best Practices

1. Version Control - Commit generated specs
2. CI/CD - Generate in build pipeline
3. Documentation - Use AsyncAPI tools for docs
4. Validation - Validate with AsyncAPI CLI
5. Keep Updated - Regenerate when contracts change

Example Scripts

The examples/basic-order-processing-contract package includes scripts for generating AsyncAPI specifications, integrated with Turborepo for easy orchestration:

Generate JSON Specification

pnpm --filter @amqp-contract-examples/basic-order-processing-contract generate:asyncapi:json

This runs scripts/generate-asyncapi-json.ts and outputs asyncapi.json.

Generate YAML Specification

pnpm --filter @amqp-contract-examples/basic-order-processing-contract generate:asyncapi:yaml

This runs scripts/generate-asyncapi-yaml.ts and outputs asyncapi.yaml.

Turborepo Integration

Both scripts are integrated with Turborepo, so you can run them across the monorepo:

# Run both generation scripts
pnpm turbo generate:asyncapi:json generate:asyncapi:yaml

The scripts automatically depend on the build task, ensuring all packages are built before generation.

Next Steps

• Learn about Defining Contracts
• Explore AsyncAPI Specification