Improve API documentation and provide an OpenAPI spec + Swagger UI

[sugan0tech]

Summary

• Provide clear, user-friendly API docs for existing and upcoming endpoints. Add an OpenAPI 3.0 spec and serve Swagger UI from the app for quick exploration.

Current Endpoints (from internal/api/router.go)

• POST /discover — same as /api/discover (duplicate for compatibility?)
• POST /api/discover — ingest server metadata and return stored id
• GET /api/servers — list all servers
• GET /api/servers/{id} — get server by id
• UI: GET / and GET /server/{id} (HTML)

Deliverables

• openapi.yaml (checked into repo) describing all public endpoints, schemas, and errors.
• Serve Swagger UI at /api/docs (read-only; no auth initially) that loads the spec.
• README section "API" with quickstart and example curl requests.
• Handler godoc comments updated to reflect behavior, errors, and status codes.
• As new app-grouping endpoints land, extend the spec accordingly.

Details

• Schemas to document:
  • Metadata (request body for discovery; response shape for servers)
  • Error responses with fields { error: string } where applicable
• Status codes and semantics:
  • 400 for invalid JSON/validation failures
  • 404 for not found
  • 409 for uniqueness conflicts (e.g., future app identifier duplicates)
  • 500 for storage errors

Tasks

• Draft openapi.yaml for current endpoints.
• Add a small /api/docs handler that serves Swagger UI (static assets) and the spec.
• Update README with API examples for existing endpoints.
• Ensure handler comments align with docs (source of truth remains the code + spec).
• Extend docs when app grouping feature lands (see related issue).

Notes

• Consider adding a versioned base path (e.g., /api/v1) when introducing breaking changes.
• If /discover and /api/discover are intended to be identical, document both; if not, clarify behavior or deprecate one.