From 3fac5059de21e8852f8e033959cb56e41ce2954d Mon Sep 17 00:00:00 2001
From: Roshan Ramani <154859727+rawsun007@users.noreply.github.com>
Date: Sat, 26 Sep 2026 21:59:02 +0530
Subject: [PATCH] docs(api): document verification and files on the compare
 endpoint (#39440)

`GET /repos/{owner}/{repo}/compare/{basehead}` reads `verification` and
`files` (both default true), the same as the commit endpoints do:

```go
verification := ctx.FormString("verification") == "" || ctx.FormBool("verification")
files := ctx.FormString("files") == "" || ctx.FormBool("files")
```

The spec only lists `output`, so generated clients cannot turn either
off. This documents both with the wording the commit endpoints already
use and regenerates the spec.

Co-authored-by: bircni <bircni@icloud.com>
---
 routers/api/v1/repo/compare.go               |  8 ++++++++
 templates/swagger/v1-openapi3.generated.json | 16 ++++++++++++++++
 templates/swagger/v1-swagger.generated.json  | 12 ++++++++++++
 3 files changed, 36 insertions(+)

diff --git a/routers/api/v1/repo/compare.go b/routers/api/v1/repo/compare.go
index fa1be491d94..05573603052 100644
--- a/routers/api/v1/repo/compare.go
+++ b/routers/api/v1/repo/compare.go
@@ -48,6 +48,14 @@ func CompareDiff(ctx *context.APIContext) {
 	//   enum:
 	//   - diff
 	//   - patch
+	// - name: verification
+	//   in: query
+	//   description: include verification for every commit (disable for speedup, default 'true')
+	//   type: boolean
+	// - name: files
+	//   in: query
+	//   description: include a list of affected files for every commit (disable for speedup, default 'true')
+	//   type: boolean
 	// responses:
 	//   "200":
 	//     "$ref": "#/responses/Compare"
diff --git a/templates/swagger/v1-openapi3.generated.json b/templates/swagger/v1-openapi3.generated.json
index ed97e4ff46b..1370e3ecaa0 100644
--- a/templates/swagger/v1-openapi3.generated.json
+++ b/templates/swagger/v1-openapi3.generated.json
@@ -20936,6 +20936,22 @@
               ],
               "type": "string"
             }
+          },
+          {
+            "description": "include verification for every commit (disable for speedup, default 'true')",
+            "in": "query",
+            "name": "verification",
+            "schema": {
+              "type": "boolean"
+            }
+          },
+          {
+            "description": "include a list of affected files for every commit (disable for speedup, default 'true')",
+            "in": "query",
+            "name": "files",
+            "schema": {
+              "type": "boolean"
+            }
           }
         ],
         "responses": {
diff --git a/templates/swagger/v1-swagger.generated.json b/templates/swagger/v1-swagger.generated.json
index 5dfecc50d77..ad6a8db84c9 100644
--- a/templates/swagger/v1-swagger.generated.json
+++ b/templates/swagger/v1-swagger.generated.json
@@ -9229,6 +9229,18 @@
             "description": "return the raw comparison as `diff` or `patch` instead of JSON",
             "name": "output",
             "in": "query"
+          },
+          {
+            "type": "boolean",
+            "description": "include verification for every commit (disable for speedup, default 'true')",
+            "name": "verification",
+            "in": "query"
+          },
+          {
+            "type": "boolean",
+            "description": "include a list of affected files for every commit (disable for speedup, default 'true')",
+            "name": "files",
+            "in": "query"
           }
         ],
         "responses": {