feat(api): Document issue/release/team params; mark legacy endpoints deprecated#117874
Merged
Merged
Conversation
github-actions
Bot
added
the
Scope: Backend
cvxluo
approved these changes
Jun 16, 2026
| { | ||
| "name": "sort", | ||
| "in": "query", | ||
| "description": "The sort order of the issues. Options include 'Last Seen' (`date`), 'First Seen' (`new`), 'Trends' (`trends`), 'Events' (`freq`), 'Users' (`user`), 'Date Added' (`inbox`), and 'Recommended' (`recommended`).", |
Contributor
There was a problem hiding this comment.
afaik recommended is feature flagged, we can omit it from here. also, this endpoint is deprecated, any new usage should be on the the organization-scoped one
gricha
force-pushed
the
gricha/feat/document-issue-release-team-params
branch
from
17d710e to
562c43a
Compare
…deprecated Surface real-but-undocumented params on three public endpoints so the generated OpenAPI schema matches what the handlers already accept: - List a Project's Issues: `sort` and `limit` (deprecated-docs JSON) - List an Organization's Releases: `project` and `per_page` (deprecated-docs JSON) - Update a Team: `name` — was accepted via the serializer's Meta.fields but hidden from the schema by `exclude_fields`; now documented as an optional field (runtime validation is unchanged; both callers use partial updates) Also marks two long-prose-deprecated endpoints with a machine-readable `deprecated: true` — List a Project's Issues (superseded by the org-scoped issues endpoint) and Submit User Feedback (superseded by the User Feedback Widget). This is a soft-deprecation annotation only: no removal is planned and runtime behavior is unchanged; it just makes the existing prose deprecation machine-readable so doc renderers and downstream consumers can act on it. The `sort` enum also drops the feature-flagged `recommended` value per review. Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
gricha
force-pushed
the
gricha/feat/document-issue-release-team-params
branch
from
562c43a to
acb35b4
Compare
gricha
changed the title
billyvg
pushed a commit
that referenced
this pull request
Jun 17, 2026
…deprecated (#117874) Surfaces real-but-undocumented params on three public endpoints so the generated OpenAPI schema matches what the handlers already accept, and marks two long-prose-deprecated endpoints with a machine-readable flag. Follow-up to #117843 — that PR added params via `@extend_schema`, but for these endpoints drf-spectacular can't surface them: the issue/release list schemas come from the hand-authored deprecated API docs, and the team `name` field was explicitly excluded. **Params documented** - **List a Project's Issues** — `sort` and `limit` (deprecated-docs JSON). `sort` omits the feature-flagged `recommended` value per review. - **List an Organization's Releases** — `project` and `per_page` (deprecated-docs JSON). - **Update a Team** — `name`. Already accepted via the serializer's `Meta.fields` but hidden by `exclude_fields`; now an explicit optional field. Runtime validation is unchanged — both callers (`TeamDetailsEndpoint.put`, SCIM `_rename_team_operation`) use partial updates. **Deprecation marked** (`deprecated: true`) - **List a Project's Issues** — superseded by the org-scoped issues endpoint. - **Submit User Feedback** — superseded by the User Feedback Widget. This is a soft-deprecation annotation only: no removal is planned and runtime behavior is unchanged. It makes the existing prose deprecation machine-readable so doc renderers and downstream consumers (e.g. Seer's code-mode typed API library, which derives its surface from this spec) can act on it. All changes are additive — no params removed, no types narrowed, no new required fields. `sentry django spectacular --validate --fail-on-warn` passes clean. Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
sehr-m
pushed a commit
that referenced
this pull request
Jun 23, 2026
…deprecated (#117874) Surfaces real-but-undocumented params on three public endpoints so the generated OpenAPI schema matches what the handlers already accept, and marks two long-prose-deprecated endpoints with a machine-readable flag. Follow-up to #117843 — that PR added params via `@extend_schema`, but for these endpoints drf-spectacular can't surface them: the issue/release list schemas come from the hand-authored deprecated API docs, and the team `name` field was explicitly excluded. **Params documented** - **List a Project's Issues** — `sort` and `limit` (deprecated-docs JSON). `sort` omits the feature-flagged `recommended` value per review. - **List an Organization's Releases** — `project` and `per_page` (deprecated-docs JSON). - **Update a Team** — `name`. Already accepted via the serializer's `Meta.fields` but hidden by `exclude_fields`; now an explicit optional field. Runtime validation is unchanged — both callers (`TeamDetailsEndpoint.put`, SCIM `_rename_team_operation`) use partial updates. **Deprecation marked** (`deprecated: true`) - **List a Project's Issues** — superseded by the org-scoped issues endpoint. - **Submit User Feedback** — superseded by the User Feedback Widget. This is a soft-deprecation annotation only: no removal is planned and runtime behavior is unchanged. It makes the existing prose deprecation machine-readable so doc renderers and downstream consumers (e.g. Seer's code-mode typed API library, which derives its surface from this spec) can act on it. All changes are additive — no params removed, no types narrowed, no new required fields. `sentry django spectacular --validate --fail-on-warn` passes clean. Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
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.
Surfaces real-but-undocumented params on three public endpoints so the generated OpenAPI schema matches what the handlers already accept, and marks two long-prose-deprecated endpoints with a machine-readable flag. Follow-up to #117843 — that PR added params via
@extend_schema, but for these endpoints drf-spectacular can't surface them: the issue/release list schemas come from the hand-authored deprecated API docs, and the teamnamefield was explicitly excluded.Params documented
sortandlimit(deprecated-docs JSON).sortomits the feature-flaggedrecommendedvalue per review.projectandper_page(deprecated-docs JSON).name. Already accepted via the serializer'sMeta.fieldsbut hidden byexclude_fields; now an explicit optional field. Runtime validation is unchanged — both callers (TeamDetailsEndpoint.put, SCIM_rename_team_operation) use partial updates.Deprecation marked (
deprecated: true)This is a soft-deprecation annotation only: no removal is planned and runtime behavior is unchanged. It makes the existing prose deprecation machine-readable so doc renderers and downstream consumers (e.g. Seer's code-mode typed API library, which derives its surface from this spec) can act on it.
All changes are additive — no params removed, no types narrowed, no new required fields.
sentry django spectacular --validate --fail-on-warnpasses clean.