Data report · 2,518 specs analyzed
State of Public OpenAPI Specs 2026
We scored every spec in the APIs.guru public directory — 2,518 real-world OpenAPI and Swagger documents covering 59,090 endpoints and 82,149 operations — for whether they carry enough information to generate a real test suite from.
51.2% of public APIs document zero error responses.
The headline numbers
Coverage across the same four dimensions our free scorer checks, averaged across the full corpus.
Average coverage by category
POST/PUT/PATCH ops with a schema — the easiest bar to clear
the weakest dimension by a wide margin
Test-readiness score distribution
Only 33.9% of specs document an error response on every single operation.
Spec format matters more than you'd think
Test-readiness climbs sharply from Swagger 2.0 to OpenAPI 3.0 to 3.1 — correlated with age as much as format, but the gap is large.
| Version | Specs | Share of corpus | Avg. score | Avg. error coverage | Avg. security coverage |
|---|---|---|---|---|---|
| Swagger 2.0 | 981 | 39% | 45.4 | 22.8% | 64.8% |
| OpenAPI 3.0 | 1,501 | 59.6% | 70.3 | 53.8% | 76.1% |
| OpenAPI 3.1 | 36 | 1.4% | 80.9 | 69.8% | 89.9% |
Best and worst categories
Categories with at least 15 specs in the corpus, ranked by average test-readiness score.
Highest-scoring
Lowest-scoring
Payment APIs score highest (compliance pressure forces documented error handling and auth). Social, location, and collaboration APIs score lowest — often internal-facing or auto-generated specs with light documentation investment.
Methodology
Source: the APIs.guru public API directory, an open, community-maintained registry of real-world OpenAPI and Swagger documents — not a curated or vendor-submitted sample. We fetched api.apis.guru/v2/list.json on 2026-08-15, downloaded the "preferred" version of all 2,529 listed APIs, and scored the 2,518 that parsed successfully as valid OpenAPI 3.x or Swagger 2.0 (11 failed to fetch or parse — mostly dead links or malformed documents — and were excluded, not scored as zero).
Scoring reuses the exact methodology behind our free OpenAPI test-readiness scorer: for every operation (path + HTTP method), we check whether it documents a 2xx success response, a 4xx/5xx error response, a request body schema (POST/PUT/PATCH only), an explicit or inherited security requirement, an operationId, and fully-described parameters. The overall score per spec is the unweighted average of the four category percentages (error coverage, security coverage, request-schema coverage, documentation completeness).
Limitations: this measures what a spec documents, not whether the live API actually behaves as documented (that requires calling the API, which we didn't do at this scale). Category labels come from APIs.guru's own x-apisguru-categories tagging, which is community-applied and not exhaustive — categories with fewer than 15 specs were excluded from the breakdown to avoid noise. "Preferred version" per API is chosen by APIs.guru, not necessarily the newest.
The collection and scoring scripts are plain Node — scripts/research/collect-openapi-corpus.mjs and scripts/research/aggregate-openapi-corpus.mjs — and the full per-spec dataset is downloadable below for independent verification.
Licensed CC BY 4.0 — reuse it, just link back to this page.
Check your own spec against this dataset
The same scoring methodology, running entirely in your browser — nothing is uploaded.
Score your spec free →Frequently asked questions
Where does this data come from?
Every spec in APIs.guru (api.apis.guru) — the largest open directory of real-world, machine-readable OpenAPI and Swagger descriptions, maintained independently of any single vendor. We fetched the "preferred" version of all 2,529 listed APIs and successfully parsed and scored 2,518 of them (11 failed to fetch or parse and were excluded, not counted as failing).What does "test-ready" mean here?
The same four-part methodology as our free scorer at /tools/openapi-coverage: does each operation document a 4xx/5xx error response (needed to generate negative tests), a security requirement (needed for authenticated vs. unauthenticated test pairs), a request body schema for POST/PUT/PATCH (needed to construct a valid payload), and complete documentation (operationId plus described parameters). This is not a syntax linter — a spec can be perfectly valid OpenAPI and still score near zero here.Is this the same scoring code as the free tool?
The same methodology, reimplemented for batch processing (see scripts/research/collect-openapi-corpus.mjs in our public repo history) so the report and the interactive tool never disagree about what counts. Paste your own spec at /tools/openapi-coverage to see exactly where it lands on this distribution.Can I use this dataset?
Yes — the full per-spec dataset is available as CSV and JSON under CC BY 4.0 (attribution required). Download links are on this page. We'd genuinely like to know what you find; link back to this page if you publish something using it.Why do Swagger 2.0 specs score so much worse than OpenAPI 3.x?
Partly the format — OpenAPI 3.x's requestBody and components/securitySchemes are more explicit and IDE/codegen-friendly than Swagger 2.0's body parameters — but mostly age: Swagger 2.0 specs in this directory skew older, and older specs get backfilled with error handling and auth less often than they're built with it from day one. Correlation, not a claim that upgrading the version number alone fixes anything.
Generate tests your spec actually supports
Forever-free Citizen Developer Edition. No credit card. Or start a 15-day Enterprise trial that mirrors the full platform.