Migrate pokemon v2/v3 scan to Huma (OpenAPI 3.1) — POC

[jfberry]

Summary

Proof-of-concept migrating POST /api/pokemon/v2/scan and POST /api/pokemon/v3/scan from hand-rolled gin handlers to Huma, so the API is self-documenting via OpenAPI 3.1. Goal: evaluate discoverability on our most complex endpoints (DNF filters + PVP) before deciding whether to migrate the rest.

• Docs: Stoplight UI at /docs, spec at /openapi.json (both public; operations are secured).
• Documented response types: new pointer-based PokemonResult; the previously-opaque Pvp interface{} is now a fully documented {little, great, ultra} PvpRankings structure. Request-side DNF filter structs are documented too.
• Serializer parity: Huma uses its own serializer (not gin's), so -tags go_json doesn't apply to it — overridden to use goccy/go-json to match the current gin setup.
• Auth: X-Golbat-Secret is now a documented apiKey security scheme + Huma middleware mirroring AuthRequired() (empty secret still disables auth).
• Legacy retired: gin PokemonScan2/3 handlers and the dead GetPokemonInArea2/3 + PokemonScan3Result removed. internalGetPokemonInArea2/3, GrpcGetPokemonInArea2/3, and the v1/search builders are untouched.

Wire compatibility

Designed to be wire-compatible with the legacy responses (v2 has a real production consumer):

• Nullable fields are *T without omitempty, so missing values still serialize as null (identical to guregu/null). A golden parity test asserts every shared scalar key is byte-identical to the legacy builder.
• v2 stays a bare array; v3 keeps its {pokemon, examined, skipped, total} wrapper; both preserve HTTP 202.
• Disabled Huma's $schema/Link: describedBy response injection (cfg.CreateHooks = nil) so v3 bodies don't gain a $schema field. Guarded by an e2e test.

Intentional divergences (documented): pvp shape changed from the legacy dynamic map (omitted empty leagues; null when disabled) to the fixed three-league struct (always emits all three, null for empty). Huma also validates request bodies more strictly (structured 422 vs gin's lenient bind) and omits the ; charset=utf-8 on Content-Type.

Test Plan

Automated (CI): builder/golden-parity, v2 bare-array & v3 wrapper shape, auth allow/reject, OpenAPI discoverability, and an httptest e2e (auth + $schema absence) all pass under go test ./... and go build -tags go_json ./....

Manual — to run against the live DB + real caller:

• Boot against the populated MariaDB; confirm no startup panic and /docs renders both operations with the PVP schema.
• Point the real v2 consumer at /api/pokemon/v2/scan and confirm it works unchanged (this is the key validation).
• Diff a captured real v2 response against the pre-migration output (expect byte-identical except the documented pvp/header divergences).
• Spot-check v3 with PVP enabled to confirm little/great/ultra populate as expected.

Design + results doc: docs/superpowers/specs/2026-05-30-huma-pokemon-v2-v3-scan-design.md

🤖 Generated with Claude Code