Added docs for the tree api (#5834)

* Added docs for the tree api

* Added missing response definition

* Fixed swagger docs

3 files changed, 135 insertions, 0 deletions

diff --git a/routers/api/v1/repo/tree.go b/routers/api/v1/repo/tree.go
index fd0bf84132..7288d6caed 100644
--- a/routers/api/v1/repo/tree.go
+++ b/routers/api/v1/repo/tree.go
@@ -16,6 +16,30 @@ import (
 
 // GetTree get the tree of a repository.
 func GetTree(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/git/trees/{sha} repository GetTree
+	// ---
+	// summary: Gets the tree of a repository.
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: sha
+	//   in: path
+	//   description: sha of the commit
+	//   type: string
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/GitTreeResponse"
 	sha := ctx.Params("sha")
 	if len(sha) == 0 {
 		ctx.Error(400, "sha not provided", nil)
diff --git a/routers/api/v1/swagger/repo.go b/routers/api/v1/swagger/repo.go
index 3e3b0ff5a4..0c9f95f962 100644
--- a/routers/api/v1/swagger/repo.go
+++ b/routers/api/v1/swagger/repo.go
@@ -133,3 +133,10 @@ type swaggerResponseAttachment struct {
 	//in: body
 	Body api.Attachment `json:"body"`
 }
+
+// GitTreeResponse
+// swagger:response GitTreeResponse
+type swaggerGitTreeResponse struct {
+	//in: body
+	Body api.GitTreeResponse `json:"body"`
+}
diff --git a/templates/swagger/v1_json.tmpl b/templates/swagger/v1_json.tmpl
index d86d1116ca..c3475abace 100644
--- a/templates/swagger/v1_json.tmpl
+++ b/templates/swagger/v1_json.tmpl
@@ -1701,6 +1701,46 @@
         }
       }
     },
+    "/repos/{owner}/{repo}/git/trees/{sha}": {
+      "get": {
+        "produces": [
+          "application/json"
+        ],
+        "tags": [
+          "repository"
+        ],
+        "summary": "Gets the tree of a repository.",
+        "operationId": "GetTree",
+        "parameters": [
+          {
+            "type": "string",
+            "description": "owner of the repo",
+            "name": "owner",
+            "in": "path",
+            "required": true
+          },
+          {
+            "type": "string",
+            "description": "name of the repo",
+            "name": "repo",
+            "in": "path",
+            "required": true
+          },
+          {
+            "type": "string",
+            "description": "sha of the commit",
+            "name": "sha",
+            "in": "path",
+            "required": true
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/responses/GitTreeResponse"
+          }
+        }
+      }
+    },
     "/repos/{owner}/{repo}/hooks": {
       "get": {
         "produces": [
@@ -7127,6 +7167,38 @@
       },
       "x-go-package": "code.gitea.io/gitea/vendor/code.gitea.io/sdk/gitea"
     },
+    "GitEntry": {
+      "description": "GitEntry represents a git tree",
+      "type": "object",
+      "properties": {
+        "mode": {
+          "type": "string",
+          "x-go-name": "Mode"
+        },
+        "path": {
+          "type": "string",
+          "x-go-name": "Path"
+        },
+        "sha": {
+          "type": "string",
+          "x-go-name": "SHA"
+        },
+        "size": {
+          "type": "integer",
+          "format": "int64",
+          "x-go-name": "Size"
+        },
+        "type": {
+          "type": "string",
+          "x-go-name": "Type"
+        },
+        "url": {
+          "type": "string",
+          "x-go-name": "URL"
+        }
+      },
+      "x-go-package": "code.gitea.io/gitea/vendor/code.gitea.io/sdk/gitea"
+    },
     "GitObject": {
       "type": "object",
       "title": "GitObject represents a Git object.",
@@ -7146,6 +7218,32 @@
       },
       "x-go-package": "code.gitea.io/gitea/vendor/code.gitea.io/sdk/gitea"
     },
+    "GitTreeResponse": {
+      "description": "GitTreeResponse returns a git tree",
+      "type": "object",
+      "properties": {
+        "sha": {
+          "type": "string",
+          "x-go-name": "SHA"
+        },
+        "tree": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/GitEntry"
+          },
+          "x-go-name": "Entries"
+        },
+        "truncated": {
+          "type": "boolean",
+          "x-go-name": "Truncated"
+        },
+        "url": {
+          "type": "string",
+          "x-go-name": "URL"
+        }
+      },
+      "x-go-package": "code.gitea.io/gitea/vendor/code.gitea.io/sdk/gitea"
+    },
     "Issue": {
       "description": "Issue represents an issue in a repository",
       "type": "object",
@@ -8290,6 +8388,12 @@
         }
       }
     },
+    "GitTreeResponse": {
+      "description": "GitTreeResponse",
+      "schema": {
+        "$ref": "#/definitions/GitTreeResponse"
+      }
+    },
     "Hook": {
       "description": "Hook",
       "schema": {