When a service's stub note does not include a spec_url, the orchestrator discovers it using the following order:
1. Explicit — use spec_url from the stub note if present. Done.
2. Infer from docs page — fetch service_url/docs (Swagger UI). Extract the spec URL from the HTML — Swagger UI always references the JSON spec it renders.
3. Guess common paths — try in order:
• /openapi.json — FastAPI default
• /swagger.json — older convention
• /spec.json — used by httpbin
• /api-docs — Spring / Node ecosystems
• /v1/openapi.json, /api/openapi.json — versioned paths
4. Fail informatively — report that spec discovery failed. User should add spec_url explicitly to the stub note.
Inferring from the docs page (step 2) is preferred over guessing (step 3) because the docs page is self-referential by design and more likely to be correct than any assumed convention.
A service stub note must contain at least:
service_url: http://example.com
# spec_url is optional — discovered automatically if absent