feat(apidocs): Hide enum values and nested fields from the schema

[azulus]

Withholding part of the public schema only works per field today. Anything finer means hand-writing an OpenApiParameter constant beside the serializer it duplicates, and the copy drifts: /replay-count/ accepted the spans data source for 52 days before its constant mentioned it, and still documents query as optional though the validator requires it.

Keys in omit_from_public_schema become dotted paths, so a choice value or a nested field can be named the way a plain field already could. The class of the field a segment names decides what the next segment means, so data_source.discover has one reading and no second keyword is needed. Deprecation takes the same {path: reason} shape and now requires a reason. Withholding the value a field falls back to also drops the default and marks the parameter required, since a default only means anything for an optional one.

Deprecating a choice is refused rather than accepted quietly: OpenAPI can express it with oneOf branches, but drf-spectacular emits a flat enum and generators collapse those branches, so the marker would reach nobody. A path may cross into a component several shapes share only when every one of them declares it, since hiding a field from a shared shape would hide it from an endpoint that never asked.

Flat names are one-segment paths, so the 40 existing declarations are unchanged and the schema is byte-identical until something adopts a path. The second commit is the first adoption. data_source comes out exactly as before, so the deprecation those constants encoded survives being derived rather than transcribed; query becomes required, which the validator declares and test_invalid_params_query_required already asserts.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f6fb5ca. Configure here.}

[cursor]

Parent check misses operation refs

Medium Severity

parents_by_component only records other schema components that hold a property $ref. It does not see a shared shape used as an operation request or response. A nested omission can therefore mutate that component and hide the field from an endpoint that never declared the path, which is the case this check is meant to block.

Additional Locations (1)

• src/sentry/apidocs/omission_apply.py#L106-L115

 

^{Reviewed by Cursor Bugbot for commit f6fb5ca. Configure here.}