feat(api): Document issue/release/team params; mark legacy endpoints 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>

Author: 2 people

api-docs/paths/events/project-issues.json

@@ -3,6 +3,7 @@
     "tags": ["Events"],
     "description": "**Deprecated**: This endpoint has been replaced with the [Organization Issues endpoint](/api/events/list-an-organizations-issues/) which\nsupports filtering on project and additional functionality.\n\nReturn a list of issues (groups) bound to a project.  All parameters are supplied as query string parameters. \n\n A default query of ``is:unresolved`` is applied. To return results with other statuses send an new query value (i.e. ``?query=`` for all results).\n\nThe ``statsPeriod`` parameter can be used to select the timeline stats which should be present. Possible values are: ``\"\"`` (disable),``\"24h\"`` (default), ``\"14d\"``\n\nUser feedback items from the [User Feedback Widget](https://docs.sentry.io/product/user-feedback/#user-feedback-widget) are built off the issue platform, so to return a list of user feedback items for a specific project, filter for `issue.category:feedback`.",
     "operationId": "List a Project's Issues",
+    "deprecated": true,
     "parameters": [
       {
         "name": "organization_id_or_slug",
@@ -54,6 +55,25 @@
           "type": "string"
         }
       },
+      {
+        "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`), and 'Date Added' (`inbox`).",
+        "schema": {
+          "type": "string",
+          "default": "date",
+          "enum": ["date", "new", "trends", "freq", "user", "inbox"]
+        }
+      },
+      {
+        "name": "limit",
+        "in": "query",
+        "description": "The maximum number of issues to return. The maximum is 100.",
+        "schema": {
+          "type": "integer",
+          "default": 100
+        }
+      },
       {
         "$ref": "../../components/parameters/pagination-cursor.json#/PaginationCursor"
       }

api-docs/paths/projects/user-feedback.json

@@ -73,6 +73,7 @@
     "tags": ["Projects"],
     "description": "*This endpoint is DEPRECATED. We document it here for older SDKs and users who are still migrating to the [User Feedback Widget](https://docs.sentry.io/product/user-feedback/#user-feedback-widget) or [API](https://docs.sentry.io/platforms/javascript/user-feedback/#user-feedback-api)(multi-platform). If you are a new user, do not use this endpoint - unless you don't have a JS frontend, and your platform's SDK does not offer a feedback API.*\n\nFeedback must be received by the server no more than 30 minutes after the event was saved.\n\nAdditionally, within 5 minutes of submitting feedback it may also be overwritten. This is useful in situations where you may need to retry sending a request due to network failures.\n\nIf feedback is rejected due to a mutability threshold, a 409 status code will be returned.\n\nNote: Feedback may be submitted with DSN authentication (see auth documentation).",
     "operationId": "Submit User Feedback",
+    "deprecated": true,
     "parameters": [
       {
         "name": "organization_id_or_slug",

api-docs/paths/releases/organization-releases.json

@@ -21,6 +21,25 @@
           "type": "string"
         }
       },
+      {
+        "name": "project",
+        "in": "query",
+        "description": "The IDs or slugs of projects to filter releases by. This parameter may be repeated to filter by multiple projects. Omit to include all accessible projects; `-1` includes all accessible projects.",
+        "schema": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      {
+        "name": "per_page",
+        "in": "query",
+        "description": "The number of releases to return per page. Default and maximum allowed is 100.",
+        "schema": {
+          "type": "integer"
+        }
+      },
       {
         "$ref": "../../components/parameters/pagination-cursor.json#/PaginationCursor"
       }

src/sentry/core/endpoints/team_details.py

@@ -1,7 +1,7 @@
 from uuid import uuid4
 
 from django.db import router, transaction
-from drf_spectacular.utils import extend_schema, extend_schema_serializer
+from drf_spectacular.utils import extend_schema
 from rest_framework import serializers, status
 from rest_framework.request import Request
 from rest_framework.response import Response
@@ -34,8 +34,12 @@
 from sentry.models.team import Team, TeamStatus
 
 
-@extend_schema_serializer(exclude_fields=["name"])
 class TeamDetailsSerializer(CamelSnakeModelSerializer):
+    name = serializers.CharField(
+        max_length=64,
+        required=False,
+        help_text="The name of the team.",
+    )
     slug = SentrySerializerSlugField(
         max_length=DEFAULT_SLUG_MAX_LENGTH,
         help_text="Uniquely identifies a team. This is must be available.",