chore: update makefile and add new tool

this tool will generate group-related swagger schemas without repeating the same comments twice in different places

Makefile

@@ -151,6 +151,7 @@ ESLINT_CONCURRENCY ?= 2
 
 SWAGGER_SPEC := templates/swagger/v1_json.tmpl
 SWAGGER_SPEC_INPUT := templates/swagger/v1_input.json
+SWAGGER_SPEC_GROUP_INPUT := templates/swagger/v1_groups.json
 SWAGGER_EXCLUDE := code.gitea.io/sdk
 
 TEST_MYSQL_HOST ?= mysql:3306
@@ -238,6 +239,8 @@ generate-swagger: $(SWAGGER_SPEC) ## generate the swagger spec from code comment
 
 $(SWAGGER_SPEC): $(GO_SOURCES) $(SWAGGER_SPEC_INPUT)
 	$(GO) run $(SWAGGER_PACKAGE) generate spec --exclude "$(SWAGGER_EXCLUDE)" --input "$(SWAGGER_SPEC_INPUT)" --output './$(SWAGGER_SPEC)'
+	$(GO) generate -v ./build_tools/...
+	$(GO) run $(SWAGGER_PACKAGE) mixin -o './$(SWAGGER_SPEC)' $(SWAGGER_SPEC) $(SWAGGER_SPEC_GROUP_INPUT)
 
 .PHONY: swagger-check
 swagger-check: generate-swagger

build_tools/swagger/main.go

@@ -0,0 +1,87 @@
+//go:generate go run main.go ../../
+
+package main
+
+import (
+	"encoding/json"
+	"log"
+	"os"
+	"path/filepath"
+	"regexp"
+)
+
+var rxPath = regexp.MustCompile("(?m)^(/repos/\\{owner})/(\\{repo})")
+
+func generatePaths(root string) map[string]any {
+	pathData := make(map[string]any)
+	endpoints := make(map[string]any)
+	fileToRead, err := filepath.Rel(root, "./templates/swagger/v1_json.tmpl")
+	if err != nil {
+		log.Fatal(err)
+	}
+	swaggerBytes, err := os.ReadFile(fileToRead)
+	if err != nil {
+		log.Fatal(err)
+	}
+	raw := make(map[string]any)
+	err = json.Unmarshal(swaggerBytes, &raw)
+	if err != nil {
+		log.Fatal(err)
+	}
+	paths := raw["paths"].(map[string]any)
+	for k, v := range paths {
+		if !rxPath.MatchString(k) {
+			// skip if this endpoint does not start with `/repos/{owner}/{repo}`
+			continue
+		}
+		// generate new endpoint path with `/group/{group_id}` in between the `owner` and `repo` params
+		nk := rxPath.ReplaceAllString(k, "$1/group/{group_id}/$2")
+		methodMap := v.(map[string]any)
+
+		for method, methodSpec := range methodMap {
+			specMap := methodSpec.(map[string]any)
+			params := specMap["parameters"].([]any)
+			params = append(params, map[string]any{
+				"description": "group ID of the repo",
+				"name":        "group_id",
+				"type":        "integer",
+				"format":      "int64",
+				"required":    true,
+				"in":          "path",
+			})
+			// i believe for...range loops create copies of each item that's iterated over,
+			// so we need to take extra care to ensure we're mutating the original map entry
+			(methodMap[method].(map[string]any))["parameters"] = params
+		}
+		endpoints[nk] = methodMap
+	}
+	pathData["paths"] = endpoints
+	return pathData
+}
+
+func writeMapToFile(filename string, data map[string]any) {
+	bytes, err := json.MarshalIndent(data, "", "\t")
+	if err != nil {
+		log.Fatal(err)
+	}
+	err = os.WriteFile(filename, bytes, 0666)
+	if err != nil {
+		log.Fatal(err)
+	}
+}
+
+func main() {
+	var err error
+	root := "../../"
+	if len(os.Args) > 1 {
+		root = os.Args[1]
+	}
+	err = os.Chdir(root)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	pathData := generatePaths(".")
+	out := "./templates/swagger/v1_groups.json"
+	writeMapToFile(out, pathData)
+}