ref(api): promote Telemetry Experience release endpoints to spectacular public docs (sentry-api-schema#76)#118005
Open
betegon wants to merge 5 commits into
Open
ref(api): promote Telemetry Experience release endpoints to spectacular public docs (sentry-api-schema#76)#118005betegon wants to merge 5 commits into
betegon wants to merge 5 commits into
Conversation
Pilot for getsentry/sentry-api-schema#76. This endpoint was documented publicly only via the legacy hand-maintained api-docs/ spec (sentence operationId, no summary), while its source method was PRIVATE and already carried a fully-migrated @extend_schema (token operation_id + summary + params + typed responses + examples). - flip GET publish_status PRIVATE -> PUBLIC so the decorator drives the spec - delete the legacy api-docs/paths/releases/organization-release-commits.json and its $ref in api-docs/openapi.json Generated spec now emits operationId=listOrganizationReleaseCommits + summary='List an Organization Release's Commits' (was the sentence with no summary). summary == old operationId, so the docs slug is unchanged.
github-actions
Bot
added
the
Scope: Backend
… spectacular public docs Migrates the rest of the team's release endpoints off the legacy hand-maintained api-docs/ system onto drf-spectacular decorators (13 ops across 6 files), completing the set started by the org-release-commits pilot. For each: flip publish_status -> PUBLIC so the decorator drives the spec, and delete the legacy api-docs path file + its $ref. Decorator parity work surfaced by the build: - list/update release-file ops still had sentence operation_ids -> tokens + summaries - createOrganizationRelease body fields (projects/headCommits/refs) needed help_text descriptions - the two file delete()s needed Response[None] (PUBLIC endpoints can't use bare Response) Summaries equal the old legacy operationIds, so docs slugs are unchanged. Verified: spectacular --validate --fail-on-warn passes; all 14 release ops emit token operationIds; 216 public ops total (unchanged); ids unique. Excludes commitfiles (owned by Issues) and deploys (unowned).
betegon
changed the title
…motion
The api docs endpoint tests validate real responses against the (now stricter,
decorator-driven) schemas, exposing two inaccuracies the loose legacy schemas
had masked:
- CommitSerializer emits author={} for authorless commits, but
CommitSerializerResponse.author only allowed a populated Author. Allow an
EmptyAuthor ({}) alongside Author so the published schema matches reality.
- The release-file upload apidocs tests forced SERVER_NAME=us.sentry.io, which
only matched the legacy POST's operation-level region server. The endpoint now
uses the standard global server (still region-templated), so drop the forced
host to match every other endpoint test.
Verified: spectacular --validate --fail-on-warn clean; the 4 previously-failing
ops pass; full releases apidocs suite (19) + commit-consumer tests (4) green.
…sponse
The release-commits endpoints serialize via the Commit registry, where
CommitWithReleaseSerializer wins — so the response includes a 'releases'
field that the declared CommitSerializerResponse omitted. The api docs tests
didn't catch it because OpenAPI response validation ignores undeclared extra
fields.
- declare list[CommitSerializerResponseWithReleases] on both release-commits
endpoints so 'releases' is part of the published contract
- make CommitReleaseSerializerResponse.ref/url/dateReleased nullable to match
what the serializer actually returns (None for releases without them)
- give the apidocs tests one authored + one authorless commit so both the
populated-author and empty-author ({}) shapes are actually validated
Verified: spectacular --validate --fail-on-warn clean; releases apidocs suite
(19) + commit-consumer tests (4) green.
The release-commits response now declares CommitSerializerResponseWithReleases (releases required), so the LIST_RELEASE_COMMITS example needs a releases entry or openapi-examples-validator (validate-api-examples / api docs test) fails with 'must have required property releases'. Verified: validate-api-examples reports no errors; releases apidocs suite (19) green.
Member
|
Why are we making all of these public? I have too little context on these endpoints to even tell if they are ready to be public and if we are ready to commit to maintaining them and not breaking them. Keeping them private gives us that freedom, but once they are public, it's way harder to do work on them |
Member
Author
|
@vgrozdanic Heyaaa! i know you're travelling that's why i didn't bother you (yet). from my understanding:
so basically, this PR moves them to our new convention. |
Member
Author
|
maybe we can loop someone else that has more context on this? |
Member
Author
|
example of them being already published https://docs.sentry.io/api/releases/list-an-organizations-releases/ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Migrates all of Telemetry Experience's release endpoints off the legacy hand-maintained
api-docs/system onto drf-spectacular@extend_schemadecorators — so their public docs entries get clean tokenoperationIds +summarys (instead of the legacy sentence operationIds with no summary). Pilot + full team sweep for getsentry/sentry-api-schema#76.14 operations across 7 source files / 7 legacy files:
…/releases/…/releases/{version}/files/…/releases/{version}/files/{file_id}/…/releases/{version}/commits/…/projects/…/releases/{version}/commits/…/projects/…/releases/{version}/files/…/projects/…/releases/{version}/files/{file_id}/For each op: flip
publish_status→PUBLICso the decorator drives the spec, and delete the legacyapi-docs/paths/releases/*.jsonfile + its$refinapi-docs/openapi.json.Decorator-parity work surfaced by the build
Promoting to PUBLIC turns on the spec-completeness checks, which required:
operation_ids → tokens + summariescreateOrganizationRelease's request body fields (projects,headCommits,refs) neededhelp_textdescriptionsdelete()s neededResponse[None](PUBLIC endpoints can't use bareResponse)Slug preservation
Each
summaryequals the endpoint's old legacyoperationIdverbatim, soslugify(summary || operationId)is unchanged — no docs-URL/SEO breakage.Verification
make build-deprecated-docs+sentry django spectacular --validate --fail-on-warn:operationId+summarysrc/sentryScope notes / sign-off
This promotes these endpoints to officially PUBLIC (a public-API stability commitment) — but they're already de-facto public via the legacy docs, so this aligns source with reality. Flagging @getsentry/telemetry-experience as owner.
Excluded: the
commitfilesendpoint (owned by Issues, and has no decorator yet) anddeploys(unowned, already de-listed). Those are tracked in the issue for their owners.Old → new doc parity (no regression)
Verified each op's old legacy
api-docs/definition against the new decorator output in the generated spec. Nothing dropped on any of the 14 — params/responses are a strict superset (the decorators document params and error codes the legacy files omitted).…/releases/environment…/releases/208,401…/releases/{version}/files/checksum,query401…/releases/{version}/files/400,401,409…/releases/{version}/files/{file_id}/401…/releases/{version}/files/{file_id}/400,401…/releases/{version}/files/{file_id}/401…/releases/{version}/commits/401…/projects/…/releases/{version}/commits/401…/projects/…/releases/{version}/files/checksum,query401…/projects/…/releases/{version}/files/400,401,409…/projects/…/releases/{version}/files/{file_id}/401…/projects/…/releases/{version}/files/{file_id}/400,401…/projects/…/releases/{version}/files/{file_id}/401Notes:
openapi-derefed.json/@sentry/api); this only relocates the source of truth from the legacy file to the decorator. No new exposure.summaryequals the old legacyoperationIdverbatim → docs slug (slugify(summary || operationId)) is byte-identical → same docs URL, no SEO/link change.publish_statusis documentation-only (read solely by the apidocs spec generator) — no access, permission, or runtime-behavior change.CommitSerializerResponseinstead of the legacy trimmedMinimalCommit— an accuracy improvement (the endpoint always returned the full serializer).