API Documentation Standards for Agent Readiness: OpenAPI vs AsyncAPI vs Smithy vs RAML
Your API documentation format directly determines whether AI agents can discover, understand, and use your service. We evaluated four API description standards through the lens of agent readiness — scoring each on D1 Discovery, D2 API Quality, and D9 Agent Experience. The results are not even close.
Why Your API Spec Format Matters for Agent Readiness
When an AI agent encounters your service for the first time, it needs to answer three questions in seconds: What can this API do? What parameters does each endpoint need? What will it return? The answers to these questions come from your API documentation spec — and the format of that spec determines whether the agent can parse it at all.
From our analysis of OpenAPI adoption across 500+ businesses, we know that the presence of a machine-readable API spec is one of the strongest predictors of a high Agent Readiness Score. Businesses with a published OpenAPI spec average 52 on ARS. Businesses without any spec average 23. But not all specs are created equal.
Four standards dominate the API documentation landscape: OpenAPI (formerly Swagger), AsyncAPI, Smithy, and RAML. Each was designed for different use cases, and each has radically different implications for how AI agents interact with your service.
Agent Readiness Scorecard: Four Standards Compared
Each standard scored on three agent-critical dimensions: D1 Discovery (can agents find it?), D2 API Quality (can agents understand it?), and D9 Agent Experience (can agents use it to generate working code?).
OpenAPI (Swagger)
v3.1 | OpenAPI Initiative (Linux Foundation) | YAML/JSON
Focus: RESTful HTTP APIs
Adoption: Dominant — used by Stripe, Twilio, GitHub, and most public APIs
Verdict: Best for Day 1 agent readiness. Most AI frameworks auto-ingest OpenAPI specs.
AsyncAPI
v3.0 | AsyncAPI Initiative | YAML/JSON
Focus: Event-driven, WebSocket, Kafka, MQTT APIs
Adoption: Growing — strong in fintech streaming, IoT, and real-time services
Verdict: Essential for webhook-heavy services. Complements OpenAPI, does not replace it.
Smithy
v2.0 | Amazon Web Services | Custom IDL (.smithy)
Focus: Protocol-agnostic API modeling
Adoption: Niche — primarily AWS services and Amazon internal tooling
Verdict: Powerful modeling language but minimal agent ecosystem support today.
RAML
v1.0 | MuleSoft (Salesforce) | YAML
Focus: RESTful API design and documentation
Adoption: Declining — concentrated in MuleSoft/Salesforce ecosystem
Verdict: Legacy standard. Convert to OpenAPI for agent readiness.
Dimension-by-Dimension Breakdown
How each standard performs on the three dimensions that matter most for agent interaction.
D1 Discovery
Can agents automatically find and parse the spec?
D2 API Quality
Does the spec fully describe request/response schemas?
D9 Agent Experience
Can an agent generate working code from the spec alone?
The Recommendation: OpenAPI First, AsyncAPI Second
For agent readiness, the recommendation is clear: publish an OpenAPI 3.1 spec for your REST API. If you also have event-driven endpoints (WebSockets, webhooks, message queues), add an AsyncAPI spec alongside it. This combination covers the vast majority of agent interaction patterns.
Smithy and RAML have legitimate use cases — Smithy for internal API governance at scale, RAML within the MuleSoft ecosystem — but neither helps agents discover or use your service. If you are currently using either, maintain it internally but generate an OpenAPI spec as your public, agent-facing documentation. Both Smithy and RAML have conversion tools that automate this.
The agent readiness impact is immediate. When AgentHermes scans a business and finds an OpenAPI spec at a well-known URL, D1 Discovery jumps by 15 to 25 points. D2 API Quality increases based on the completeness of the spec — schemas, examples, descriptions, and error codes all contribute. The documentation dimension alone can move a business from Bronze to Silver tier.
Do This
- Publish OpenAPI 3.1 at /openapi.json
- Add AsyncAPI for webhook/WebSocket endpoints
- Include examples for every endpoint
- Link spec from agent-card.json and llms.txt
Avoid This
- Publishing only RAML or Smithy without OpenAPI
- Using Swagger 2.0 (upgrade to OpenAPI 3.1)
- Generating specs without descriptions or examples
- Hiding your spec behind authentication
How AgentHermes Detects and Scores API Documentation
The AgentHermes scanner probes 12 well-known paths during every scan, including /openapi.json, /swagger.json, /api-docs, and /asyncapi.json. The scanner validates the spec structure, counts documented endpoints, checks for schema completeness, and factors everything into D1 and D2 scores.
Across 500+ scans, here is what we found: 34% of businesses with public APIs publish an OpenAPI spec. 3% publish AsyncAPI. Zero publish Smithy or RAML at a discoverable URL. The GraphQL vs REST comparison shows a similar pattern — introspection-enabled GraphQL endpoints score well on D2 but lag on D1 because agents default to REST discovery patterns.
Frequently Asked Questions
Should I use OpenAPI even if I have WebSocket endpoints?
Yes — use OpenAPI for your REST endpoints and AsyncAPI for your WebSocket/event endpoints. They are complementary, not competing. An agent-ready service with both gets higher D1 and D2 scores because agents can discover REST tools via OpenAPI and subscribe to real-time events via AsyncAPI. Publish both specs at well-known URLs.
We use Smithy internally at AWS. Does that hurt our agent readiness?
Smithy is an excellent API modeling language — the issue is agent discoverability. Most AI agent frameworks cannot parse .smithy files directly. The fix is simple: use Smithy internally for modeling and governance, but publish an OpenAPI spec alongside it for agent consumption. Smithy has built-in OpenAPI conversion. Run it as part of your CI pipeline.
Is RAML dead?
Not dead, but no longer evolving. MuleSoft still supports it, and existing RAML specs work fine within the Salesforce ecosystem. But for agent readiness, RAML is a liability — zero major AI frameworks auto-discover or parse RAML. If you have RAML specs today, convert them to OpenAPI 3.1. Tools like oas-raml-converter handle this automatically.
How does AgentHermes detect API documentation standards?
The AgentHermes scanner checks well-known paths (/openapi.json, /swagger.json, /api-docs, /asyncapi.json) and probes response headers for content-type hints. It also follows links from llms.txt, agent-card.json, and HTML meta tags. OpenAPI detection contributes directly to D1 Discovery and D2 API Quality scores. AsyncAPI detection is a D2 bonus.
Is your API documentation agent-ready?
Run a free Agent Readiness Scan. AgentHermes detects your API spec format, evaluates completeness, and scores you across all 9 dimensions. See exactly what agents see when they find your service.