RFC: Optional “Explain this AsyncAPI” AI Assistant for Docs

[Devnil434]

Summary

This RFC proposes adding an optional, read-only AI assistant to the AsyncAPI website that helps users understand AsyncAPI documents by explaining selected sections in plain English.

The feature is purely additive, opt-in, and does not modify existing content or the AsyncAPI spec. Its goal is to improve learning, onboarding, and comprehension without affecting current site behavior.

Motivation

AsyncAPI documents are expressive but can be challenging to interpret, especially for:

• New users learning the specification
• Developers onboarding to an existing AsyncAPI file
• Contributors trying to understand complex or deeply nested schemas

Currently, users often leave the website to:

• Search for explanations elsewhere
• Ask repetitive questions on Slack or GitHub
• Use external AI tools without AsyncAPI-specific context

This feature would add a lightweight explanation layer directly on asyncapi.com, helping users understand what they’re reading without changing what’s written.

Proposal

Introduce an “Explain this AsyncAPI” feature that allows users to request a plain-English explanation of a selected AsyncAPI section (e.g. channels, components.schemas, or a specific operation).

Key characteristics

✅ Optional and feature-flagged
✅ Read-only (no editing or generation of specs)
✅ On-demand (no build-time execution)
✅ Gracefully disabled if not configured
✅ No changes to existing docs, routes, or MDX

User Experience (Concept)

• User highlights or selects a section of an AsyncAPI document

• Clicks an “Explain this” button

• A side panel or modal displays:

• What this section represents

• When it’s typically used

Common pitfalls or misunderstandings

Simple conceptual examples (if applicable)

If the feature is disabled or unavailable, the button does not appear.

Technical Overview (High Level)

Frontend

• Reusable React/MDX component (e.g. )
• Triggered only by user interaction
• No impact on static rendering

Backend

• Optional serverless function (Netlify)
• Receives a schema fragment and context
• Returns a textual explanation

Safety

• Server-side API calls only
• Input size limits
• Rate-limited
• No content persistence
• No environment variables required unless enabled

Why this is not a breaking change

• Does not change existing content or rendering
• Does not introduce required configuration
• Does not affect build or deployment
• Does not alter AsyncAPI semantics
• Can be fully disabled via a feature flag

If disabled, the website behaves exactly as it does today.

Alternatives Considered

External AI tools

→ Loses AsyncAPI-specific context and fragments the learning experience.

More written documentation

→ Helpful, but does not scale to every possible spec structure or user question.

This proposal complements documentation rather than replacing it.

Rollout Plan (Proposed)

• Phase 1 – Docs only (static AsyncAPI examples)
• Phase 2 – Playground / user-provided AsyncAPI files (optional)
• Phase 3 – Advanced explanations (e.g. diff explanations across versions)

Each phase can be independently evaluated and stopped if needed.

Maintenance & Ownership

The feature is intentionally:

• Isolated
• Optional
• Easy to disable or remove

I’m happy to:

• Own the implementation
• Address feedback
• Maintain the feature if accepted

Feedback Requested

I’d appreciate feedback on:

• Whether this aligns with the project’s goals
• Any concerns around scope, safety, or maintenance
• Whether a small proof-of-concept would be helpful before proceeding

Thanks for your time and for maintaining AsyncAPI 🙌