[FEATURE] Add `stats` command to display AsyncAPI document metrics
- Dominant language
- TypeScript
- Stars
- 272
- Forks
- 375
- Avg merge
- 3h 22m
- Merged PRs (30d)
- 8
Description
### Why do we need this improvement?
Currently, there's no quick way to get an overview of what's inside an AsyncAPI document without manually opening and inspecting it.
**Problems this solves:**
1) **Slower code reviews** – Reviewers often need to open and scan large files to understand the scope of changes (e.g., how many channels or messages were added).
2) **Limited quick discovery** – New contributors must read significant parts of the document to understand the API surface and supported protocols.
3) **Manual documentation metrics** – Teams often want basic API statistics for READMEs or internal docs, but currently have to extract them manually.
4) **Lack of simple complexity tracking** – While diffs show what changed, there is no straightforward way to track how the API grows over time using consistent metrics.
5) **CI/CD reporting limitations** – Pipelines cannot easily extract structured, high-level metrics without custom scripts.
**Example scenario:**
```bash
# Current workflow (painful):
1. Open asyncapi.yaml in editor
2. Scroll through 500+ lines
3. Manually count channels, messages, schemas
4. Check server configurations
5. Look for version info
```
This becomes especially tedious when working with multiple AsyncAPI files or reviewing PRs.
### How will this change help?
Adding a `stats` command will provide:
### 1. **Instant Document Overview**
Get a comprehensive summary in seconds instead of minutes of manual inspection.
### 2. **Faster Code Reviews**
Reviewers can quickly see:
- "This PR adds 5 new channels and 12 messages"
- "Schema count increased from 10 to 25"
- Changes in operations (send/receive ratio)
### 3. **Better Documentation**
Auto-generate API statistics for README files:
```bash
asyncapi stats ./asyncapi.yaml --format markdown >> README.md
```
### 4. **Quality Insights**
Identify issues like:
- Missing descriptions or examples
- Unused schemas
- Channels without servers
- Operations without documentation
### 5. **CI/CD Integration**
```bash
asyncapi stats ./asyncapi.yaml --format json > metrics.json
# Feed into monitoring dashboards, track API growth
```
### 6. **Onboarding Experience**
New developers get instant understanding:
- What protocols are used (Kafka, MQTT, AMQP)
- How many integration points exist
- Overall API complexity
**Real-world impact:** Similar to how `git status` gives quick repo overview, `asyncapi stats` gives quick API overview.
### Screenshots
N/A - This is a CLI command. Will provide example output once implemented.
**Expected output example:**
```
AsyncAPI Document Statistics
Document Info
Version: 3.0.0
Title: Streetlight API
API Version: 1.0.0
Servers: 3
├─ production (mqtt)
├─ development (mqtt)
└─ test (amqp)
Channels: 5
Messages: 12
Operations: 8 (4 send, 4 receive)
Schemas: 18
Security Schemes: 2
File Stats
Size: 12.3 KB
Lines: 450
Format: YAML
Quality Checks
• 3 messages missing examples
• 2 operations without descriptions
```
### How could it be implemented/designed?
***This is a rough implementation outline intended to show feasibility and alignment with the current CLI architecture, not a final design.***
### Implementation Approach
**Tech Stack:**
- TypeScript (what the CLI already uses)
- AsyncAPI Parser v3 (already there)
- oclif (CLI framework already in place)
**Basic Structure:**
```
src/commands/stats.ts # The main command
src/core/analyzer.ts # Extracts the metrics
src/core/formatter.ts # Formats output
```
**How it works:**
```typescript
async function analyzeDocument(filePath: string) {
const { document } = await parse(filePath);
const metrics = {
channels: document.channels().all().length,
messages: document.messages().all().length,
operations: document.operations().all().length,
schemas: document.components().schemas().all().length,
servers: document.servers().all().length
};
return formatOutput(metrics, options);
}
```
No new dependencies needed - everything's already in the CLI.
### 🚧 Breaking changes
No
### 👀 Have you checked for similar open issues?
- [x] I checked and didn't find a 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
Assessment
This issue has not been assessed yet.