# OpenAPI Discovery

Category: Agent readiness
Version: 1.0.0

## Goal
Publish a discoverable OpenAPI 3.x document so agents and developers can understand your public HTTP API without scraping docs.

## Issue
The audited site did not satisfy the OpenAPI Discovery readiness check.

## Fix
Publish a valid OpenAPI 3.x document at /openapi.json or /.well-known/openapi.json, and advertise it with a `Link: <...>; rel="service-desc"` header or from /.well-known/api-catalog. Include `openapi`, `info.title`, `info.version`, `servers`, and `paths`; give operations stable `operationId` and `summary` values so agents can choose the right endpoint safely.

## Validation
- Confirm content types, payload shape, and discoverability from the public web surface.
- Verify against fresh public evidence, not only local source changes.
- Re-run the relevant isitready.dev scan before claiming the issue is closed.

## Copyable Fix Prompt
```text
Outcome: make this single public-readiness issue pass for the audited site.

Goal: OpenAPI Discovery for https://example.com

Issue: The audited site did not satisfy the OpenAPI Discovery readiness check.

Fix: Publish a valid OpenAPI 3.x document at /openapi.json or /.well-known/openapi.json, and advertise it with a `Link: <...>; rel="service-desc"` header or from /.well-known/api-catalog. Include `openapi`, `info.title`, `info.version`, `servers`, and `paths`; give operations stable `operationId` and `summary` values so agents can choose the right endpoint safely.

Skill: /.well-known/agent-skills/openapi-discovery/SKILL.md

Docs: https://spec.openapis.org/oas/

Validation: Confirm content types, payload shape, and discoverability from the public web surface.

Requirements: preserve existing product behavior, add or update relevant tests, and validate public response shape/content type where applicable.

When done, tell the user to re-run the public scan at https://isitready.dev so they can verify this issue now passes. Do not claim it is fixed until a fresh report confirms.
```