asyncapi / asyncapi/markdown-template
[Bug] Incorrect server rendering in AsyncAPI v3: protocol prefix added (`kafka://`) instead of just host
- Dominant language
- JavaScript
- Stars
- 36
- Forks
- 38
- Avg merge
- 3m
- Merged PRs (30d)
- 3
Description
### Describe the bug.
When generating Markdown documentation from an AsyncAPI v3.0.0 specification using `@asyncapi/markdown-template@2.0.0`, the server section renders the full URL with protocol prefix (e.g., `kafka://kafka.example.com:9092/`) instead of just the `host` value as defined in the v3 spec (`kafka.example.com:9092`).
This is incorrect because AsyncAPI v3.0.0 uses separate `host` (required) and `pathname` (optional) fields, with `protocol` separate — no combined `url` with protocol prefix like in v2.
### Expected behavior
The server should render as:
**Host:** `kafka.example.com:9092`
**Protocol:** `kafka`
No `kafka://` prefix or trailing `/` should appear unless `pathname` is defined.
### Screenshots
### How to Reproduce
1. Use this minimal AsyncAPI v3.0.0 YAML file (`asyncapi.yaml`):
```yaml
asyncapi: '3.0.0'
id: 'urn:example:com:demo:app'
info:
title: Demo Event-Driven API
version: '1.0.0'
servers:
production:
host: kafka.example.com:9092
protocol: kafka
description: Production Kafka broker
channels:
userSignedUp:
address: user/signedup
messages:
UserSignedUp:
$ref: '#/components/messages/UserSignedUp'
operations:
sendUserSignedUp:
action: send
channel:
$ref: '#/channels/userSignedUp'
messages:
- $ref: '#/channels/userSignedUp/messages/UserSignedUp'
components:
messages:
UserSignedUp:
name: UserSignedUp
title: User Signed Up Event
contentType: application/json
payload:
type: object
properties:
userId: { type: string, description: Unique user identifier }
email: { type: string, format: email }
required: [userId, email]
```
2 .Generate Markdown documentation using the latest template:
```yaml
npx -p @asyncapi/cli \
asyncapi generate fromTemplate \
asyncapi.yaml \
@asyncapi/markdown-template \
-o output-md
```
3. Open the generated file: output-md/asyncapi.md
**Observed result:**
In the Servers section, it shows:
URL: `kafka://kafka.example.com:9092/`
**Expected:**
Host: `kafka.example.com:9092`
### 🖥️ Device Information [optional]
- Operating System (OS): Windows(WSL2)
- Browser: Chrome(Latest)
- Browser Version: Latest
### 👀 Have you checked for similar open issues?
- [x] I checked and didn't find similar issue
### 🏢 Have you read the Contributing Guidelines?
- [x] I have read the [Contributing Guidelines](https://github.com/asyncapi/.github/blob/master/CONTRIBUTING.md)
### Are you willing to work on this issue ?
Yes I am willing to submit a PR!
Contributor guide
Research direction
Reproduce the issue with the minimal asyncapi.yaml and the documented AsyncAPI CLI command, then inspect output-md/asyncapi.md in the Servers section. Done means the output shows Host as kafka.example.com:9092 and Protocol as kafka, without a protocol prefix or trailing slash unless pathname is defined.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, nodejs
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 65/100