api specs

README.md

@@ -34,29 +34,39 @@ Production-ready full-stack web app based on your original live score concept.
 8. Podium is determined automatically.
 9. If top-3 tie exists, podium tie-break stage appears.
 
-## API Highlights
+## API Documentation (OpenAPI)
 
-Public:
+Interactive docs are now built in:
 
-- `GET /api/health`
-- `GET /api/state`
+- Swagger UI: `GET /api/docs`
+- OpenAPI JSON: `GET /api/openapi.json`
 
-Admin:
+### Testing with Auth in Swagger UI
 
-- `POST /api/admin/login`
-- `POST /api/admin/logout`
-- `POST /api/admin/players`
-- `PUT /api/admin/players/:id`
-- `DELETE /api/admin/players/:id`
-- `PUT /api/admin/scores/:stage/:id`
-- `POST /api/admin/scores/:stage/:id/advice`
-- `POST /api/admin/scores/:stage/reset`
+1. Open `/api/docs`.
+2. Use the **Login & Authorize** form at the top:
+   - Username: `datwyler` (default)
+   - Password: `datwyler` (default)
+3. The page calls `POST /api/admin/login`, retrieves the token, and auto-authorizes Swagger.
+4. Use **Try it out** on any admin endpoint.
 
-Stages:
+### Stage Values
+
+For score update/proof/advice endpoints (`/api/admin/scores/{stage}/...`), use:
+
+- `prelim_r1`
+- `prelim_r2`
+- `prelim_r3`
+- `final_r1`
+- `final_r2`
+- `prelim_tiebreak`
+- `final_tiebreak`
+
+For reset endpoint (`POST /api/admin/scores/{stage}/reset`), use:
 
 - `preliminary`
-- `prelim_tiebreak`
 - `final`
+- `prelim_tiebreak`
 - `final_tiebreak`
 
 ## Local Development