chore(api): Switch create team to body params & clarify name vs slug (#…

…56458)

### Name vs Slug for Team Create & Update
Clarify the usage of `name` vs `slug` by: 
1. Marking `name` as deprecated
2. Explicitly mentioning `slug` is used for the interface
3. Switching display order of `name` and `slug`
4. Marking `name` as deprecated in our request body schema.

Ideally we would require `slug` so I wouldn't have to include the extra
bit in the description and b/c we use `slug` over `name` for everything
now, but that would be a breaking change.

### Create Before + After
![Screenshot 2023-09-19 at 5 45 11
PM](https://github.com/getsentry/sentry/assets/67301797/172e9565-3a7f-4fb3-b4f6-4ea2291d6e86)
![Screenshot 2023-09-19 at 5 44 20
PM](https://github.com/getsentry/sentry/assets/67301797/31162906-b171-410c-bd73-fba651fcf783)

### Update Before + After
![Screenshot 2023-09-19 at 5 45 02
PM](https://github.com/getsentry/sentry/assets/67301797/079a85e7-7462-4382-a7c4-35ec70c9453e)
![Screenshot 2023-09-19 at 6 31 47
PM](https://github.com/getsentry/sentry/assets/67301797/b695500d-7749-4bba-8f86-af7319fa90cc)

api-docs/paths/teams/by-slug.json

@@ -79,7 +79,7 @@
   },
   "put": {
     "tags": ["Teams"],
-    "description": "Update various attributes and configurable settings for the given team.",
+    "description": "Update various attributes settings for the given team.",
     "operationId": "Update a Team",
     "parameters": [
       {
@@ -105,16 +105,16 @@
       "content": {
         "application/json": {
           "schema": {
-            "required": ["name"],
             "type": "object",
             "properties": {
-              "name": {
+              "slug": {
                 "type": "string",
-                "description": "The new name for the team."
+                "description": "Uniquely identifies a team and is used for the interface. Must be available."
               },
-              "slug": {
+              "name": {
                 "type": "string",
-                "description": "A new slug for the team. It has to be unique and available."
+                "description": "**`[DEPRECATED]`** The name for the team.",
+                "deprecated": true
               }
             }
           },

src/sentry/api/endpoints/organization_teams.py

@@ -2,7 +2,7 @@
 
 from django.db import IntegrityError, router, transaction
 from django.db.models import Q
-from drf_spectacular.utils import OpenApiResponse, extend_schema
+from drf_spectacular.utils import OpenApiResponse, extend_schema, extend_schema_serializer
 from rest_framework import serializers, status
 from rest_framework.exceptions import ParseError
 from rest_framework.request import Request
@@ -48,15 +48,25 @@ class OrganizationTeamsPermission(OrganizationPermission):
     }
 
 
+@extend_schema_serializer(exclude_fields=["idp_provisioned"], deprecate_fields=["name"])
 class TeamPostSerializer(serializers.Serializer, PreventNumericSlugMixin):
-    name = serializers.CharField(max_length=64, required=False, allow_null=True, allow_blank=True)
     slug = serializers.RegexField(
         DEFAULT_SLUG_PATTERN,
+        help_text="""Uniquely identifies a team and is used for the interface. If not
+        provided, it is automatically generated from the name.""",
         max_length=50,
         required=False,
         allow_null=True,
         error_messages={"invalid": DEFAULT_SLUG_ERROR_MESSAGE},
     )
+    name = serializers.CharField(
+        help_text="""**`[DEPRECATED]`** The name for the team. If not provided, it is
+        automatically generated from the slug""",
+        max_length=64,
+        required=False,
+        allow_null=True,
+        allow_blank=True,
+    )
     idp_provisioned = serializers.BooleanField(required=False, default=False)
 
     def validate(self, attrs):
@@ -163,10 +173,6 @@ def should_add_creator_to_team(self, request: Request):
         operation_id="Create a New Team",
         parameters=[
             GlobalParams.ORG_SLUG,
-            GlobalParams.name("The name for the team.", required=True),
-            GlobalParams.slug(
-                "Optional slug for the team. If not provided a slug is generated from the name."
-            ),
         ],
         request=TeamPostSerializer,
         responses={
@@ -179,7 +185,8 @@ def should_add_creator_to_team(self, request: Request):
     )
     def post(self, request: Request, organization, **kwargs) -> Response:
         """
-        Create a new team bound to an organization.
+        Create a new team bound to an organization. Requires at least one of the `name`
+        or `slug` body params to be set.
         """
         serializer = TeamPostSerializer(data=request.data)