[mre]

Summary

• add realistic response data examples for every documented analytics endpoint
• infer OpenAPI response schemas from the curated examples instead of using generic array data
• include the full response shape with meta fields and example data in Swagger UI

Notes on numeric strings

Some values that look numeric are intentionally documented as strings because that is the current live API behavior. This is a bit weird, but it is correct right now.

Examples include MySQL computed/aggregate values such as:

• spotifyPlaysSum.spotify_starts
• spotifyPlaysSum.spotify_streams
• spotifyPlaysSum.spotify_listeners
• decimal/percentage fields like spotify_listeners_percent, quarter1_combined, and Apple LTR quarter values

I verified this against https://api.openpodcast.dev with podcast ID 16. For example, spotifyPlaysSum currently returns:

{
  "podcast_id": 16,
  "spotify_total_episodes": "49",
  "spotify_starts": "99942",
  "spotify_streams": "76882",
  "spotify_listeners": "8389",
  "spotify_followers": "3626"
}

The report app also already handles this behavior in practice, e.g. by parsing values for charts and by formatting numeric strings in gauges. A future API cleanup could normalize these fields to numbers where safe, but this PR documents the API shape as it exists today.

Validation

• npm run build
• npx prettier --check src/config/generate-query-docs.ts src/config/query-examples.ts
• generated Swagger spec check: 20 documented paths, 20 paths with examples
• started the local API against a fresh local Docker MySQL DB and fetched:
  • http://localhost:8080/api-docs.json -> 200
  • http://localhost:8080/api-docs/ -> 200
• served local spec check: 20 documented paths, 20 paths with examples, no missing examples
• compared example field names/types against live API responses for podcast ID 16