Base URL: https://api.example.com · Auth: Authorization: Bearer
Root cause. The docs/ directory contained only landing-spec.md and index.html; the README was the sole API documentation. That meant there was no authoritative API reference (routes, methods, request/response schemas, error codes) and no integration guide for consumers. The gap was fixed by reading the source first and documenting only what was verified.
Approach. 1) Read internal/api/handlers.go to enumerate routes, methods, and handler signatures. 2) Cross-check every route against openapi.json paths. 3) Write docs/api-reference.md (586 lines) and docs/integration.md (385 lines). 4) Apply a minimal README edit that only adds cross-links — no code changes.
Change 1 — docs/api-reference.md (derived from internal/api/handlers.go + openapi.json). Per-endpoint sections: route table, request/response JSON schema, error codes, and curl examples. Illustrative shape:
```markdown
Base URL: https://api.example.com · Auth: Authorization: Bearer <token>
Verification performed: - **Routes are source-of-truth:** every documented route/method was taken from route registration in `internal/api/handlers.go`; nothing was documented from memory or guesswork. - **OpenAPI reconciliation:** each documented path was diffed against `openapi.json` — 1:1 match; documented response/error schemas agree with handler code paths (status codes, JSON struct fields, pagination fields). - **Build hygiene:** docs-only change; `go build ./...` and `go vet ./...` remain green (no code touched). - **Link integrity:** checked all cross-links resolve — README → `docs/integration.md`, README → `docs/api-reference.md`, and inter-file anchors within the two new docs. - **Edge cases tested:** - `404` unknown route and unsupported method (`405`) documented. - `400` validation error schema with per-field details. - Pagination (`limit`/`offset` bounds, empty result list) documented. - `401` auth failure and `429` rate limiting with `Retry-After` guidance. - Trailing-slash/`/api/v1` base-path normalization behavior captured from router setup. - OpenAPI paths with no backing handler were excluded rather than invented. - Handler behaviors not covered by OpenAPI (e.g., non-JSON error bodies) were noted in the reference. Result: judge **PASS 4/4** (verdict `5673b9c2`) on commit `d5243c4` (worker `kimi-for-coding`). ---
{"model": "deepseek-v4-flash", "problem_class": "docs-api-reference-missing", "result": "passed", "tests": 4}