Serve OpenAPI 3.0 spec at /openapi.v1.json (#37038)

Add a build-time conversion step that transforms the existing Swagger
2.0 spec into an OpenAPI 3.0 spec. The OAS3 spec is served alongside the
existing Swagger 2.0 spec, enabling API clients that require OAS3 to
generate code directly from Gitea's API.

This is not to be an answer to how gitea handles OAS3 long term,
but a way to use what we have to move a step forward.

---------

Signed-off-by: wxiaoguang <wxiaoguang@gmail.com>
Co-authored-by: Claude (Opus 4.7) <noreply@anthropic.com>
Co-authored-by: silverwind <me@silverwind.io>
Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>

Author: 4 people

.editorconfig

@@ -18,7 +18,7 @@ indent_style = tab
 [templates/custom/*.tmpl]
 insert_final_newline = false
 
-[templates/swagger/v1_json.tmpl]
+[templates/swagger/*_json.tmpl]
 indent_style = space
 insert_final_newline = false
 

Makefile

@@ -151,6 +151,7 @@ ESLINT_CONCURRENCY ?= 2
 SWAGGER_SPEC := templates/swagger/v1_json.tmpl
 SWAGGER_SPEC_INPUT := templates/swagger/v1_input.json
 SWAGGER_EXCLUDE := code.gitea.io/sdk
+OPENAPI3_SPEC := templates/swagger/v1_openapi3_json.tmpl
 
 TEST_MYSQL_HOST ?= mysql:3306
 TEST_MYSQL_DBNAME ?= testgitea
@@ -233,7 +234,7 @@ TAGS_PREREQ := $(TAGS_EVIDENCE)
 endif
 
 .PHONY: generate-swagger
-generate-swagger: $(SWAGGER_SPEC) ## generate the swagger spec from code comments
+generate-swagger: $(SWAGGER_SPEC) $(OPENAPI3_SPEC) ## generate the swagger spec from code comments
 
 $(SWAGGER_SPEC): $(GO_SOURCES) $(SWAGGER_SPEC_INPUT)
 	$(GO) run $(SWAGGER_PACKAGE) generate spec --exclude "$(SWAGGER_EXCLUDE)" --input "$(SWAGGER_SPEC_INPUT)" --output './$(SWAGGER_SPEC)'
@@ -255,14 +256,29 @@ swagger-validate: ## check if the swagger spec is valid
 	$(GO) run $(SWAGGER_PACKAGE) validate './$(SWAGGER_SPEC)'
 	@$(SED_INPLACE) -E -e 's|"basePath":( *)"/(.*)"|"basePath":\1"\2"|g' './$(SWAGGER_SPEC)' # remove the prefix slash from basePath
 
+.PHONY: generate-openapi3
+generate-openapi3: $(OPENAPI3_SPEC) ## generate the OpenAPI 3.0 spec from the Swagger 2.0 spec
+
+$(OPENAPI3_SPEC): $(SWAGGER_SPEC) build/generate-openapi.go $(wildcard build/openapi3gen/*.go)
+	$(GO) run build/generate-openapi.go
+
+.PHONY: openapi3-check
+openapi3-check: generate-openapi3
+	@diff=$$(git diff --color=always '$(OPENAPI3_SPEC)'); \
+	if [ -n "$$diff" ]; then \
+		echo "Please run 'make generate-openapi3' and commit the result:"; \
+		printf "%s" "$${diff}"; \
+		exit 1; \
+	fi
+
 .PHONY: checks
 checks: checks-frontend checks-backend ## run various consistency checks
 
 .PHONY: checks-frontend
 checks-frontend: lockfile-check svg-check ## check frontend files
 
 .PHONY: checks-backend
-checks-backend: tidy-check swagger-check fmt-check swagger-validate security-check ## check backend files
+checks-backend: tidy-check swagger-check openapi3-check fmt-check swagger-validate security-check ## check backend files
 
 .PHONY: lint
 lint: lint-frontend lint-backend lint-spell ## lint everything

assets/go-licenses.json

@@ -0,0 +1,97 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+// generate-openapi converts Gitea's Swagger 2.0 spec into an OpenAPI 3.0 spec.
+//
+// Gitea generates a Swagger 2.0 spec from code annotations (make generate-swagger).
+// This tool converts it to OAS3 so that SDK generators and tools that require
+// OAS3 (e.g. progenitor for Rust) can consume it directly. The conversion also
+// deduplicates inline enum definitions into named schema components, producing
+// cleaner SDK output with proper enum types instead of anonymous strings.
+//
+// Run: go run build/generate-openapi.go
+// Output: templates/swagger/v1_openapi3_json.tmpl
+
+//go:build ignore
+
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"log"
+	"os"
+	"regexp"
+	"sort"
+	"strings"
+
+	"code.gitea.io/gitea/build/openapi3gen"
+
+	"github.com/getkin/kin-openapi/openapi3"
+)
+
+const (
+	swaggerSpecPath = "templates/swagger/v1_json.tmpl"
+	openapi3OutPath = "templates/swagger/v1_openapi3_json.tmpl"
+
+	appSubUrlVar = "{{.SwaggerAppSubUrl}}"
+	appVerVar    = "{{.SwaggerAppVer}}"
+
+	appSubUrlPlaceholder = "GITEA_APP_SUB_URL_PLACEHOLDER"
+	appVerPlaceholder    = "0.0.0-gitea-placeholder"
+)
+
+var (
+	appSubUrlRe = regexp.MustCompile(regexp.QuoteMeta(appSubUrlVar))
+	appVerRe    = regexp.MustCompile(regexp.QuoteMeta(appVerVar))
+
+	enumScanDirs = []string{
+		"modules/structs",
+		"modules/commitstatus",
+	}
+)
+
+func main() {
+	astEnumMap, err := openapi3gen.ScanSwaggerEnumTypes(enumScanDirs)
+	if err != nil {
+		log.Fatalf("scanning swagger:enum annotations: %v", err)
+	}
+	names := make([]string, 0, len(astEnumMap))
+	for _, n := range astEnumMap {
+		names = append(names, n)
+	}
+	sort.Strings(names)
+	fmt.Fprintf(os.Stderr, "discovered %d swagger:enum types: %s\n", len(names), strings.Join(names, ", "))
+
+	data, err := os.ReadFile(swaggerSpecPath)
+	if err != nil {
+		log.Fatalf("reading swagger spec: %v", err)
+	}
+
+	cleaned := appSubUrlRe.ReplaceAll(data, []byte(appSubUrlPlaceholder))
+	cleaned = appVerRe.ReplaceAll(cleaned, []byte(appVerPlaceholder))
+
+	oas3, err := openapi3gen.Convert(cleaned, astEnumMap)
+	if err != nil {
+		log.Fatalf("converting to openapi 3.0: %v", err)
+	}
+
+	oas3.Servers = openapi3.Servers{
+		{URL: appSubUrlPlaceholder + "/api/v1"},
+	}
+
+	out, err := json.MarshalIndent(oas3, "", "  ")
+	if err != nil {
+		log.Fatalf("marshaling openapi 3.0: %v", err)
+	}
+
+	result := strings.ReplaceAll(string(out), appSubUrlPlaceholder, appSubUrlVar)
+	result = strings.ReplaceAll(result, appVerPlaceholder, appVerVar)
+	result = strings.TrimSpace(result)
+
+	if err := os.WriteFile(openapi3OutPath, []byte(result), 0o644); err != nil {
+		log.Fatalf("writing openapi 3.0 spec: %v", err)
+	}
+
+	fmt.Printf("Generated %s\n", openapi3OutPath)
+}