[zmofei]

The Statistics API team now publishes the spec in openapi-specs (mapbox/api-analytics/openapi/statistics-api.yaml). It is vendored into openapi/ by the maintainer sync like every other spec, and replaces the hand-written custom-openapi/statistics/ copy.

The spec adds a dimensions query parameter, and the API returns the per-browser/country/host breakdown only when asked. mapbox usage gets a matching --dimensions flag: the pinning test requires every spec parameter to have one, and without it a debug build panics on mapbox usage. Without the flag the request is unchanged. The text tips and the 422 hint now mention --dimensions.

Verified against the real API with a dev build: without the flag the request is the same as before and each product's dimensions is {}; --dimensions hosts returns only hosts; an invalid value returns 422 with the message the spec documents. Not verified: the content of a non-empty breakdown, because the test account's requests have no host, browser or country.

[mattpodwysocki]

Thanks Mofei, this is a nice cleanup. Dropping the hand-written spec for the upstream one is where we wanted to end up, and I like that a request without --dimensions stays byte-for-byte the same, with a test pinning it.

A few small things, none blocking:

• The comment above the is_boolean branch in fetch still says "today's three parameters". It's four now.
• Could --dimensions get a clap value parser (comma delimiter plus browsers/countries/hosts as possible values)? A typo would then fail right away instead of costing a round trip and a 422, and the values would show up in help and completions.
• The 422 hint mentions --dimensions even when it wasn't passed. Fine as is, but it could check whether the flag was set.
• The sample JSON in docs/commands.md predates the opt-in breakdown. The note covers it, but a fresh capture would be nicer when you get a chance.

Approving, happy to see these in a follow-up.