docs(api): military bbox endpoints under-documented — empty param descriptions, no enums/examples/required-bbox contract

[koala73]

Problem

The public REST endpoints for military bases/flights (and, to a lesser degree, cable-health) are only partially documented. A consumer cannot self-serve the request contract from the published docs, which is what led to the silent-empty confusion tracked in the companion DX issue.

What exists today

• Auto-generated OpenAPI — docs/api/MilitaryService.openapi.json, docs/api/InfrastructureService.openapi.json (proto-driven).
• Narrative mdx — docs/military-tracking.mdx, docs/infrastructure-cascade.mdx. These are architecture docs (how the frontend consumes the RPCs), not consumer API references — they list endpoints in a prose table with no params, examples, or curl.

Gaps

1. Empty param descriptions on list-military-bases. The bases proto (proto/worldmonitor/military/v1/list_military_bases.proto) has no field comments, so every param in the OpenAPI (ne_lat, ne_lon, sw_lat, sw_lon, zoom, type, kind, country) renders with a blank description. (Contrast list_military_flights.proto, which does comment its fields → those descriptions are populated. This is the model to copy.)

2. Valid enum values are undocumented. The handler hard-validates type/kind/country and returns empty on a miss, but the accepted values live only in code, not in the proto/OpenAPI:

   • type ∈ us-nato, china, russia, uk, france, india, italy, uae, turkey, japan, other
   • kind ∈ base, airfield, naval_base, military, barracks, bunker, trench, training_area, checkpoint, shelter, ammunition, office, obstacle_course, nuclear_explosion_site, range
   • country = ISO-3166 alpha-2, uppercase
     (server/worldmonitor/military/v1/list-military-bases.ts:12-20)

3. The "bbox is effectively required" contract is unstated. OpenAPI marks all bbox params required: false, yet omitting them yields an empty result. The docs should state that a bounding box (all four of sw_lat/sw_lon/ne_lat/ne_lon) is required to get any data.

4. Zoom-tiering behavior is undocumented. Results are filtered by zoom: zoom < 5 → tier-1 bases only; zoom 5–7 → tier ≤ 2; zoom ≥ 8 → all tiers (list-military-bases.ts:200-202). A low-zoom world-extent query looking "empty-ish" is by design and should be documented.

5. No request examples / curl on any of these operations in the OpenAPI or mdx.

6. cable-health semantics could be clearer. get-cable-health takes no params and returns cables: {} when no cable has an active anomaly (i.e. all healthy — only anomalous cables appear). The proto comment already hints at this ("cables with active signals"); worth surfacing the "absent = OK / empty map = all healthy" convention in the consumer docs so an empty response isn't read as "broken."

Proposed fix

• Add field comments to list_military_bases.proto (mirror the flights proto style) and regenerate OpenAPI → fills the blank descriptions.
• Document the type/kind enums and country format (as OpenAPI enum/description, sourced from the handler's VALID_TYPES/VALID_KINDS).
• State the required-bbox contract and the zoom-tiering rule in docs/military-tracking.mdx (or a dedicated consumer reference), with at least one working curl example per endpoint.
• Add a one-line "empty map = all cables healthy" note to the infrastructure/cable-health docs.

Acceptance criteria

• Every param on both military endpoints has a non-empty OpenAPI description.
• type/kind accepted values and country format are discoverable from the docs.
• Docs state that a bbox is required and explain zoom-tiering, with runnable examples.

Related

• Companion DX issue: military bbox endpoints return a silent empty 200 on missing/all-zero bbox (surface 400/debug header).

[koala73]

Companion DX/behavior issue: #4595

[koala73]

Rolled up under umbrella #4599 (subsumed by systemic root causes #3/#4 + long-tail). The full-surface audit found the same gap classes across all 34 services, not just military.

[koala73]

Split into the systemic child issues under #4599: this military instance is covered by #4604 (required), #4605 (enums), and the long-tail checklist in #4599. Keeping open as the service-specific tracker until those land.