quality(apidocs): document org repo commits with drf-spectacular (#94984)

part of
https://github.com/getsentry/sentry/pull/new/jferg/doc-commits-api

Author: JoshFerge

api-docs/openapi.json

@@ -97,9 +97,6 @@
     "/api/0/organizations/{organization_id_or_slug}/repos/": {
       "$ref": "paths/organizations/repos.json"
     },
-    "/api/0/organizations/{organization_id_or_slug}/repos/{repo_id}/commits/": {
-      "$ref": "paths/organizations/repo-commits.json"
-    },
     "/api/0/projects/": {
       "$ref": "paths/projects/index.json"
     },

api-docs/paths/organizations/repo-commits.json

@@ -1,14 +1,42 @@
 from collections import defaultdict
 from collections.abc import Mapping
+from datetime import datetime
+from typing import NotRequired, TypedDict
 
 from sentry.api.serializers import Serializer, register, serialize
+from sentry.api.serializers.models.pullrequest import PullRequestSerializerResponse
 from sentry.api.serializers.models.release import Author, get_users_for_authors
+from sentry.api.serializers.models.repository import RepositorySerializerResponse
 from sentry.models.commit import Commit
 from sentry.models.commitauthor import CommitAuthor
 from sentry.models.pullrequest import PullRequest
 from sentry.models.repository import Repository
 
 
+class CommitSerializerResponse(TypedDict):
+    id: str
+    message: str | None
+    dateCreated: datetime
+    pullRequest: PullRequestSerializerResponse | None
+    suspectCommitType: str
+
+    repository: NotRequired[RepositorySerializerResponse]
+    author: NotRequired[Author]
+
+
+class CommitReleaseSerializerResponse(TypedDict):
+    version: str
+    shortVersion: str
+    ref: str
+    url: str
+    dateReleased: datetime
+    dateCreated: datetime
+
+
+class CommitSerializerResponseWithReleases(CommitSerializerResponse):
+    releases: list[CommitReleaseSerializerResponse]
+
+
 def get_users_for_commits(item_list, user=None) -> Mapping[str, Author]:
     authors = list(
         CommitAuthor.objects.get_many_from_cache([i.author_id for i in item_list if i.author_id])
@@ -66,8 +94,8 @@ def get_attrs(self, item_list, user, **kwargs):
 
         return result
 
-    def serialize(self, obj, attrs, user, **kwargs):
-        d = {
+    def serialize(self, obj: Commit, attrs, user, **kwargs) -> CommitSerializerResponse:
+        d: CommitSerializerResponse = {
             "id": obj.key,
             "message": obj.message,
             "dateCreated": obj.date_added,
@@ -102,17 +130,29 @@ def get_attrs(self, item_list, user, **kwargs):
             attrs[item]["releases"] = releases_by_commit[item.id]
         return attrs
 
-    def serialize(self, obj, attrs, user, **kwargs):
+    def serialize(self, obj, attrs, user, **kwargs) -> CommitSerializerResponseWithReleases:
         data = super().serialize(obj, attrs, user)
-        data["releases"] = [
-            {
-                "version": r.version,
-                "shortVersion": r.version,
-                "ref": r.ref,
-                "url": r.url,
-                "dateReleased": r.date_released,
-                "dateCreated": r.date_added,
-            }
-            for r in attrs["releases"]
-        ]
-        return data
+        ret: CommitSerializerResponseWithReleases = {
+            "id": data["id"],
+            "message": data["message"],
+            "dateCreated": data["dateCreated"],
+            "pullRequest": data["pullRequest"],
+            "suspectCommitType": data["suspectCommitType"],
+            "releases": [
+                {
+                    "version": r.version,
+                    "shortVersion": r.version,
+                    "ref": r.ref,
+                    "url": r.url,
+                    "dateReleased": r.date_released,
+                    "dateCreated": r.date_added,
+                }
+                for r in attrs["releases"]
+            ],
+        }
+        if "repository" in data:
+            ret["repository"] = attrs["repository"]
+        if "author" in data:
+            ret["author"] = attrs["user"]
+
+        return ret

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

@@ -1,10 +1,24 @@
+from datetime import datetime
+from typing import TypedDict
+
 from sentry.api.serializers import Serializer, register, serialize
-from sentry.api.serializers.models.release import get_users_for_authors
+from sentry.api.serializers.models.release import Author, get_users_for_authors
+from sentry.api.serializers.models.repository import RepositorySerializerResponse
 from sentry.models.commitauthor import CommitAuthor
 from sentry.models.pullrequest import PullRequest
 from sentry.models.repository import Repository
 
 
+class PullRequestSerializerResponse(TypedDict):
+    id: str
+    title: str | None
+    message: str | None
+    dateCreated: datetime
+    repository: RepositorySerializerResponse
+    author: Author
+    externalUrl: str
+
+
 def get_users_for_pull_requests(item_list, user=None):
     authors = list(
         CommitAuthor.objects.filter(id__in=[i.author_id for i in item_list if i.author_id])
@@ -39,7 +53,7 @@ def get_attrs(self, item_list, user, **kwargs):
 
         return result
 
-    def serialize(self, obj, attrs, user, **kwargs):
+    def serialize(self, obj: PullRequest, attrs, user, **kwargs) -> PullRequestSerializerResponse:
         return {
             "id": obj.key,
             "title": obj.title,

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

@@ -1,10 +1,25 @@
+from datetime import datetime
+from typing import TypedDict
+
 from sentry.api.serializers import Serializer, register
 from sentry.models.repository import Repository
 
 
+class RepositorySerializerResponse(TypedDict):
+    id: str
+    name: str
+    url: str | None
+    provider: dict[str, str]
+    status: str
+    dateCreated: datetime
+    integrationId: str | None
+    externalSlug: str | None
+    externalId: str | None
+
+
 @register(Repository)
 class RepositorySerializer(Serializer):
-    def serialize(self, obj, attrs, user, **kwargs):
+    def serialize(self, obj: Repository, attrs, user, **kwargs) -> RepositorySerializerResponse:
         external_slug = None
         integration_id = None
         if obj.integration_id:

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

@@ -1,3 +1,4 @@
+from drf_spectacular.utils import OpenApiExample, OpenApiParameter, extend_schema
 from rest_framework.request import Request
 from rest_framework.response import Response
 
@@ -7,28 +8,68 @@
 from sentry.api.bases.organization import OrganizationEndpoint
 from sentry.api.exceptions import ResourceDoesNotExist
 from sentry.api.paginator import DateTimePaginator
-from sentry.api.serializers import serialize
+from sentry.api.serializers.base import serialize
+from sentry.api.serializers.models.commit import CommitSerializerResponse
+from sentry.apidocs.constants import (
+    RESPONSE_BAD_REQUEST,
+    RESPONSE_FORBIDDEN,
+    RESPONSE_NOT_FOUND,
+    RESPONSE_UNAUTHORIZED,
+)
+from sentry.apidocs.parameters import GlobalParams
+from sentry.apidocs.utils import inline_sentry_response_serializer
 from sentry.models.commit import Commit
 from sentry.models.repository import Repository
 
 
 @region_silo_endpoint
+@extend_schema(tags=["Organizations"])
 class OrganizationRepositoryCommitsEndpoint(OrganizationEndpoint):
     owner = ApiOwner.INTEGRATIONS
     publish_status = {
-        "GET": ApiPublishStatus.UNKNOWN,
+        "GET": ApiPublishStatus.PUBLIC,
     }
 
+    @extend_schema(
+        operation_id="List a Repository's Commits",
+        parameters=[
+            GlobalParams.ORG_ID_OR_SLUG,
+            OpenApiParameter(
+                name="repo_id",
+                description="The repository ID.",
+                required=True,
+                type=str,
+                location="path",
+            ),
+        ],
+        responses={
+            200: inline_sentry_response_serializer(
+                "CommitSerializerResponse",
+                list[CommitSerializerResponse],
+            ),
+            400: RESPONSE_BAD_REQUEST,
+            401: RESPONSE_UNAUTHORIZED,
+            403: RESPONSE_FORBIDDEN,
+            404: RESPONSE_NOT_FOUND,
+        },
+        examples=[
+            OpenApiExample(
+                name="Repository Commits",
+                value=[
+                    {
+                        "dateCreated": "2018-11-06T21:19:58.536Z",
+                        "id": "acbafc639127fd89d10f474520104517ff1d709e",
+                        "message": "Initial commit from Create Next App",
+                        "suspectCommitType": "",
+                        "pullRequest": None,
+                    }
+                ],
+            ),
+        ],
+    )
     def get(self, request: Request, organization, repo_id) -> Response:
         """
         List a Repository's Commits
-        ```````````````````````````
-
-        Return a list of commits for a given repository.
-
-        :pparam string organization_id_or_slug: the id or slug of the organization
-        :pparam string repo_id: the repository ID
-        :auth: required
         """
         try:
             repo = Repository.objects.get(id=repo_id, organization_id=organization.id)