chore(apidocs): publish ProjectEnvironmentsEndpoint (#78700)

https://www.notion.so/sentry/Publish-ProjectEnvironmentsEndpoint-09420056cd144504844428e7eea839eb?pvs=4


![image](https://github.com/user-attachments/assets/702f4d87-147b-49ac-be4b-19d5bb91b1e6)

Author: isabellaenriquez

src/sentry/api/endpoints/organization_environments.py

@@ -1,5 +1,3 @@
-from typing import TypedDict
-
 from drf_spectacular.utils import extend_schema
 from rest_framework.request import Request
 from rest_framework.response import Response
@@ -10,18 +8,14 @@
 from sentry.api.bases import OrganizationEndpoint
 from sentry.api.helpers.environments import environment_visibility_filter_options
 from sentry.api.serializers import serialize
+from sentry.api.serializers.models.environment import EnvironmentSerializerResponse
 from sentry.apidocs.constants import RESPONSE_BAD_REQUEST, RESPONSE_FORBIDDEN
 from sentry.apidocs.examples.environment_examples import EnvironmentExamples
 from sentry.apidocs.parameters import EnvironmentParams, GlobalParams
 from sentry.apidocs.utils import inline_sentry_response_serializer
 from sentry.models.environment import Environment, EnvironmentProject
 
 
-class OrganizationEnvironmentResponseType(TypedDict):
-    id: int
-    name: str
-
-
 @extend_schema(tags=["Environments"])
 @region_silo_endpoint
 class OrganizationEnvironmentsEndpoint(OrganizationEndpoint):
@@ -35,7 +29,7 @@ class OrganizationEnvironmentsEndpoint(OrganizationEndpoint):
         parameters=[GlobalParams.ORG_ID_OR_SLUG, EnvironmentParams.VISIBILITY],
         responses={
             200: inline_sentry_response_serializer(
-                "OrganizationEnvironmentResponse", list[OrganizationEnvironmentResponseType]
+                "OrganizationEnvironmentResponse", list[EnvironmentSerializerResponse]
             ),
             400: RESPONSE_BAD_REQUEST,
             403: RESPONSE_FORBIDDEN,

src/sentry/api/endpoints/project_environments.py

@@ -1,3 +1,4 @@
+from drf_spectacular.utils import OpenApiResponse, extend_schema
 from rest_framework.request import Request
 from rest_framework.response import Response
 
@@ -6,33 +7,42 @@
 from sentry.api.bases.project import ProjectEndpoint
 from sentry.api.helpers.environments import environment_visibility_filter_options
 from sentry.api.serializers import serialize
+from sentry.api.serializers.models.environment import EnvironmentProjectSerializerResponse
+from sentry.apidocs.constants import RESPONSE_FORBIDDEN, RESPONSE_NOT_FOUND, RESPONSE_UNAUTHORIZED
+from sentry.apidocs.examples.environment_examples import EnvironmentExamples
+from sentry.apidocs.parameters import EnvironmentParams, GlobalParams
+from sentry.apidocs.utils import inline_sentry_response_serializer
 from sentry.models.environment import EnvironmentProject
 
 
+@extend_schema(tags=["Environments"])
 @region_silo_endpoint
 class ProjectEnvironmentsEndpoint(ProjectEndpoint):
     publish_status = {
-        "GET": ApiPublishStatus.UNKNOWN,
+        "GET": ApiPublishStatus.PUBLIC,
     }
 
+    @extend_schema(
+        operation_id="List a Project's Environments",
+        parameters=[
+            GlobalParams.ORG_ID_OR_SLUG,
+            GlobalParams.PROJECT_ID_OR_SLUG,
+            EnvironmentParams.VISIBILITY,
+        ],
+        responses={
+            200: inline_sentry_response_serializer(
+                "ListProjectEnvironments", list[EnvironmentProjectSerializerResponse]
+            ),
+            400: OpenApiResponse(description="Invalid value for 'visibility'."),
+            401: RESPONSE_UNAUTHORIZED,
+            403: RESPONSE_FORBIDDEN,
+            404: RESPONSE_NOT_FOUND,
+        },
+        examples=EnvironmentExamples.GET_PROJECT_ENVIRONMENTS,
+    )
     def get(self, request: Request, project) -> Response:
         """
-        List a Project's Environments
-        ```````````````````````````````
-
-        Return environments for a given project.
-
-        :qparam string visibility: when omitted only visible environments are
-                                   returned. Set to ``"hidden"`` for only hidden
-                                   environments, or ``"all"`` for both hidden
-                                   and visible environments.
-
-        :pparam string organization_id_or_slug: the id or slug of the organization the project
-                                          belongs to.
-
-        :pparam string project_id_or_slug: the id or slug of the project.
-
-        :auth: required
+        Lists a project's environments.
         """
 
         queryset = (

src/sentry/api/serializers/models/environment.py

@@ -1,5 +1,6 @@
 from collections import namedtuple
 from datetime import timedelta
+from typing import TypedDict
 
 from django.utils import timezone
 
@@ -11,15 +12,28 @@
 StatsPeriod = namedtuple("StatsPeriod", ("segments", "interval"))
 
 
+class EnvironmentSerializerResponse(TypedDict):
+    id: str
+    name: str
+
+
+class EnvironmentProjectSerializerResponse(TypedDict):
+    id: str
+    name: str
+    isHidden: bool
+
+
 @register(Environment)
 class EnvironmentSerializer(Serializer):
-    def serialize(self, obj, attrs, user, **kwargs):
+    def serialize(self, obj: Environment, attrs, user, **kwargs) -> EnvironmentSerializerResponse:
         return {"id": str(obj.id), "name": obj.name}
 
 
 @register(EnvironmentProject)
 class EnvironmentProjectSerializer(Serializer):
-    def serialize(self, obj, attrs, user, **kwargs):
+    def serialize(
+        self, obj: EnvironmentProject, attrs, user, **kwargs
+    ) -> EnvironmentProjectSerializerResponse:
         return {
             "id": str(obj.id),
             "name": obj.environment.name,

src/sentry/apidocs/examples/environment_examples.py

@@ -7,15 +7,27 @@ class EnvironmentExamples:
             "List an Organization's Environments",
             value=[
                 {
-                    "id": 1,
+                    "id": "1",
                     "name": "Production",
                 },
                 {
-                    "id": 2,
+                    "id": "2",
                     "name": "Staging",
                 },
             ],
             status_codes=["200"],
             response_only=True,
         )
     ]
+
+    GET_PROJECT_ENVIRONMENTS = [
+        OpenApiExample(
+            "List a Project's Environments",
+            value=[
+                {"id": "1", "name": "Production", "isHidden": False},
+                {"id": "2", "name": "Staging", "isHidden": True},
+            ],
+            status_codes=["200"],
+            response_only=True,
+        )
+    ]

src/sentry/apidocs/parameters.py

@@ -95,7 +95,8 @@ class EnvironmentParams:
         location="query",
         required=False,
         type=str,
-        description="""The visibility of the environments to filter by. The options are: `all`, `hidden`, `visible`. Defaults to `visible`.""",
+        description="""The visibility of the environments to filter by. Defaults to `visible`.""",
+        enum=["all", "hidden", "visible"],
     )