What it is
OpenAPI (Swagger) is the lingua franca for HTTP APIs. When present, an agent can read the spec and know every endpoint, every parameter, every response shape. The usual discovery paths:
- Via the API Catalog (check 09)
service-descentry /openapi.jsonor/openapi.yaml/api/openapi.json/.well-known/openapi.json
Remediation Prompt
I want to improve my site's agent readiness. Please implement the following fix for OpenAPI Discovery across our codebase. Instructions: Please fix the OpenAPI Discovery issue on my site so it is agent-ready.
How we test it
- Look up
service-descURLs in the API Catalog result (if check 09 passed) - Otherwise probe the common paths above
- Parse JSON or YAML; validate minimum OpenAPI structure (
openapiversion field +paths)
Pass Warn Fail Matrix
| Condition | Status | Score |
|---|---|---|
| Valid OpenAPI discovered via API Catalog link | pass | 1.0 |
| Valid OpenAPI discovered at a common path | pass | 1.0 |
| Found but malformed | warn | 0.5 |
| None found | not_applicable (most content sites have no API) | — |
Remediation Prompt
If you offer an API, publish its OpenAPI spec:
1. Generate openapi.yaml (or .json) from your API codebase. Use 3.1.x if possible.
2. Host it at https://api.example.com/openapi.yaml (absolute, CORS-permitted for agents).
3. Reference it from /.well-known/api-catalog (see check 09) as a `service-desc` link, with the correct media-type (application/yaml or application/json).
4. Keep it fresh — generate in CI from the source of truth, not maintained by hand.
Test Fixtures
pass-via-catalog.jsonpass-well-known.jsonwarn-invalid.yamlna-none.json