Most APIs ship with documentation. Most developers still churn in the first 10 minutes.
The gap between “we have docs” and “a developer can ship an integration this afternoon” is measurable. API-Clarity is an open-source tool that measures it.
What API-Clarity Does
API-Clarity takes an OpenAPI or Swagger spec — either uploaded as a file, fetched from a URL, or discovered automatically from a docs page — and produces a DX score from 0 to 100.
The score breaks down across 5 categories:
| Category | Points | What It Checks |
|---|---|---|
| Structural Analysis | 40 | Descriptions, response examples, error codes, parameter docs |
| Authentication | 20 | Security schemes, auth flow clarity, credential acquisition |
| Code Samples | 15 | Python, Node.js, cURL via x-code-samples |
| Error Handling | 15 | Error coverage, format consistency, troubleshooting guidance |
| Rate Limiting | 10 | Rate limit docs, retry strategy |
There is also a fintech compliance bonus that checks for PCI DSS awareness, SOC 2, GDPR, idempotency, and webhook security. This does not affect the 100-point base score but gives you a separate compliance percentage.
Output is a letter grade (A+ through F), a category breakdown with specific findings, and a prioritized recommendation list.
Why Specs, Not Portals
The tool analyzes what is in the spec file, not what is on the documentation website. This is intentional.
When a developer uses an SDK, an AI coding assistant, or an API explorer, those tools consume the spec — not the portal. If the spec is thin, every downstream tool produces a degraded experience regardless of how good the website looks.
Stripe has excellent documentation at stripe.com/docs. Their raw OpenAPI spec scores 51/100. The delta is entirely in spec-level metadata that most teams never think to add.
The Scoring Model
Structural Analysis (40 points) is weighted highest because it is the foundation. A developer cannot build on an endpoint they do not understand. This category checks whether every endpoint has a description, whether success and error responses are documented with examples, and whether parameters have types and descriptions.
Authentication (20 points) is weighted second because auth friction is the most common reason developers abandon an integration before it starts. The scorer checks whether security schemes are defined, whether the spec explains how to acquire credentials, and whether token refresh flows are documented.
Code Samples (15 points) checks for x-code-samples extensions in the spec. This is the single highest-leverage addition most teams can make — the information already exists in quickstart guides, it just needs to be embedded in the spec where SDK generators and AI assistants can find it.
Error Handling (15 points) checks both specific status codes (4xx, 5xx) and default error responses. It also checks for consistent error format across endpoints and presence of troubleshooting guidance.
Rate Limiting (10 points) checks whether rate limits are documented in the spec, including specific numbers and retry guidance.
How to Run It
The quickest path is the web interface:
- Go to clarifyintel.com/tools/api-clarity
- Upload your spec file or paste a URL
- Get your score in under 10 seconds
For CLI or CI integration:
git clone https://github.com/clarifyintel/api-clarity
cd api-clarity/backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# Analyze a local file
python -m app.cli analyze your-spec.yaml
# Analyze from a URL
python -m app.cli analyze --url https://your-api.com/openapi.json
# JSON output for CI pipelines
python -m app.cli analyze your-spec.yaml --jsonThe JSON output mode is useful for setting a score threshold in CI — fail the build if documentation quality drops below a defined floor.
What the Scores Mean in Practice
Based on scoring real APIs, here is what score ranges typically indicate:
80-100 (A/A+): The spec carries enough metadata for SDK generators, AI assistants, and API explorers to produce useful output without supplemental documentation. Rare. Requires intentional investment.
60-79 (B/C): Solid foundation with gaps. Usually missing code samples and response examples. Developers can ship integrations but will spend time in the portal.
40-59 (D): Descriptions exist but metadata is thin. Auth and error handling are underspecified. This is where most production APIs land, including Stripe and GitHub’s raw specs.
0-39 (F): The spec was generated from code with minimal annotation. A developer using only the spec cannot ship a working integration.
The industry average for fintech APIs is 67/100. Most teams do not know where they stand until they measure.
What to Fix First
If your score is below 60, the highest-leverage fixes in order are:
- Add
x-code-samplesto your top 10 endpoints with curl, Python, and Node.js examples (+15 points available) - Add response body examples to every endpoint for both success and error cases (+8-10 points)
- Add a description to every parameter that currently has none (+5-8 points)
- Document auth credential acquisition in the security scheme description (+3-5 points)
These four changes typically move a D-grade spec to a B without touching any code.
API-Clarity is open source under the MIT license. Source at github.com/clarifyintel/api-clarity. Built by ClarifyIntel.