feat: Adds async deepdown template

[jpvajda]

PR Summary

Adds a new async API template to be used with Deepdown and fixes some output issues have thorough testing.

Brief Summary: Fixed AsyncAPI Documentation Generation Issues

Problems Identified:

1. Missing Agent API: All AsyncAPI channels were overwriting each other, only showing the last processed channel
2. Broken Channel Names: Titles showed # Channel instead of # speak Channel, # agent Channel, etc.
3. Server Information: Displayed [object Object] instead of actual server names
4. HTML Entity Encoding: Text showed ' instead of ' and < instead of <

Root Causes:

• {{@key}} variable replacement wasn't working in outputPattern, causing file collisions
• Template variables with @ prefix work for file paths but not template content
• Handlebars defaults to HTML escaping for security, but we're generating Markdown

Technical Fixes Applied:

AsyncAPI Template (asyncapi.deepdown):

• File separation: Used {{@pathName}}/index.md for reliable directory creation
• Channel names: Changed {{@key}} → {{pathName}} in template content
• Server info: Fixed iteration from {{this}} → {{this.host}} ({{this.protocol}})
• Raw text: Converted {{description}} → {{{description}}} for all text fields

OpenAPI Template (openapi.deepdown):

• HTML entities: Applied same raw text fixes for descriptions, summaries, and parameter names

Result:

✅ Complete documentation: All 3 channels (speak, listen, agent) now generate separate files
✅ Proper naming: Channel names display correctly in titles and metadata
✅ Server details: Shows actual server hostnames instead of object references
✅ Clean text: All apostrophes, quotes, and brackets render properly without HTML entities

The "uploads" (documentation generation) now work correctly for the entire AsyncAPI specification.

Testing

To fully validate the output just run:

ASYNC API

deepdown build ../deepgram-api-specs/asyncapi.yml ../deepgram-api-specs/.deepgram/asyncapi.deepdown --output test-output/async-api --resolve-refs --resolve-security

Open API

deepdown build ../deepgram-api-specs/openapi.yml ../deepgram-api-specs/.deepgram/openapi.deepdown --output test-output/open-api --resolve-refs --resolve-security

Or review the test output generated here: deepgram/deepdown#2

NOTE: Only includes async output data.

---

• To see the specific tasks where the Asana app for GitHub is being used, see below:
  • https://app.asana.com/0/0/1210525738681641