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>

modules/structs/admin_user.go

@@ -30,7 +30,7 @@ type CreateUserOption struct {
 	// Whether the user has restricted access privileges
 	Restricted *bool `json:"restricted"`
 	// User visibility level: public, limited, or private
-	Visibility string `json:"visibility" binding:"In(,public,limited,private)"`
+	Visibility UserVisibility `json:"visibility" binding:"In(,public,limited,private)"`
 
 	// For explicitly setting the user creation timestamp. Useful when users are
 	// migrated from other systems. When omitted, the user's creation timestamp
@@ -79,5 +79,5 @@ type EditUserOption struct {
 	// Whether the user has restricted access privileges
 	Restricted *bool `json:"restricted"`
 	// User visibility level: public, limited, or private
-	Visibility string `json:"visibility" binding:"In(,public,limited,private)"`
+	Visibility UserVisibility `json:"visibility" binding:"In(,public,limited,private)"`
 }

modules/structs/org.go

@@ -22,7 +22,7 @@ type Organization struct {
 	// The location of the organization
 	Location string `json:"location"`
 	// The visibility level of the organization (public, limited, private)
-	Visibility string `json:"visibility"`
+	Visibility UserVisibility `json:"visibility"`
 	// Whether repository administrators can change team access
 	RepoAdminChangeTeamAccess bool `json:"repo_admin_change_team_access"`
 	// username of the organization
@@ -60,8 +60,7 @@ type CreateOrgOption struct {
 	// The location of the organization
 	Location string `json:"location" binding:"MaxSize(50)"`
 	// possible values are `public` (default), `limited` or `private`
-	// enum: ["public","limited","private"]
-	Visibility string `json:"visibility" binding:"In(,public,limited,private)"`
+	Visibility UserVisibility `json:"visibility" binding:"In(,public,limited,private)"`
 	// Whether repository administrators can change team access
 	RepoAdminChangeTeamAccess bool `json:"repo_admin_change_team_access"`
 }
@@ -79,8 +78,7 @@ type EditOrgOption struct {
 	// The location of the organization
 	Location *string `json:"location" binding:"MaxSize(50)"`
 	// possible values are `public`, `limited` or `private`
-	// enum: ["public","limited","private"]
-	Visibility *string `json:"visibility" binding:"In(,public,limited,private)"`
+	Visibility *UserVisibility `json:"visibility" binding:"In(,public,limited,private)"`
 	// Whether repository administrators can change team access
 	RepoAdminChangeTeamAccess *bool `json:"repo_admin_change_team_access"`
 }

modules/structs/org_team.go

@@ -15,9 +15,8 @@ type Team struct {
 	// The organization that the team belongs to
 	Organization *Organization `json:"organization"`
 	// Whether the team has access to all repositories in the organization
-	IncludesAllRepositories bool `json:"includes_all_repositories"`
-	// enum: ["none","read","write","admin","owner"]
-	Permission string `json:"permission"`
+	IncludesAllRepositories bool            `json:"includes_all_repositories"`
+	Permission              AccessLevelName `json:"permission"`
 	// example: ["repo.code","repo.issues","repo.ext_issues","repo.wiki","repo.pulls","repo.releases","repo.projects","repo.ext_wiki"]
 	// Deprecated: This variable should be replaced by UnitsMap and will be dropped in later versions.
 	Units []string `json:"units"`
@@ -34,9 +33,8 @@ type CreateTeamOption struct {
 	// The description of the team
 	Description string `json:"description" binding:"MaxSize(255)"`
 	// Whether the team has access to all repositories in the organization
-	IncludesAllRepositories bool `json:"includes_all_repositories"`
-	// enum: ["read","write","admin"]
-	Permission string `json:"permission"`
+	IncludesAllRepositories bool                `json:"includes_all_repositories"`
+	Permission              RepoWritePermission `json:"permission"`
 	// example: ["repo.actions","repo.code","repo.issues","repo.ext_issues","repo.wiki","repo.ext_wiki","repo.pulls","repo.releases","repo.projects","repo.ext_wiki"]
 	// Deprecated: This variable should be replaced by UnitsMap and will be dropped in later versions.
 	Units []string `json:"units"`
@@ -53,9 +51,8 @@ type EditTeamOption struct {
 	// The description of the team
 	Description *string `json:"description" binding:"MaxSize(255)"`
 	// Whether the team has access to all repositories in the organization
-	IncludesAllRepositories *bool `json:"includes_all_repositories"`
-	// enum: ["read","write","admin"]
-	Permission string `json:"permission"`
+	IncludesAllRepositories *bool               `json:"includes_all_repositories"`
+	Permission              RepoWritePermission `json:"permission"`
 	// example: ["repo.code","repo.issues","repo.ext_issues","repo.wiki","repo.pulls","repo.releases","repo.projects","repo.ext_wiki"]
 	// Deprecated: This variable should be replaced by UnitsMap and will be dropped in later versions.
 	Units []string `json:"units"`

modules/structs/repo.go

@@ -8,6 +8,15 @@ import (
 	"time"
 )
 
+// ObjectFormatName is the git hash algorithm used by a repository.
+// swagger:enum ObjectFormatName
+type ObjectFormatName string
+
+const (
+	ObjectFormatSHA1   ObjectFormatName = "sha1"
+	ObjectFormatSHA256 ObjectFormatName = "sha256"
+)
+
 // Permission represents a set of permissions
 type Permission struct {
 	Admin bool `json:"admin"` // Admin indicates if the user is an administrator of the repository.
@@ -114,8 +123,7 @@ type Repository struct {
 	Internal                      bool             `json:"internal"`
 	MirrorInterval                string           `json:"mirror_interval"`
 	// ObjectFormatName of the underlying git repository
-	// enum: ["sha1","sha256"]
-	ObjectFormatName string `json:"object_format_name"`
+	ObjectFormatName ObjectFormatName `json:"object_format_name"`
 	// swagger:strfmt date-time
 	MirrorUpdated time.Time     `json:"mirror_updated"`
 	RepoTransfer  *RepoTransfer `json:"repo_transfer,omitempty"`
@@ -153,8 +161,7 @@ type CreateRepoOption struct {
 	// enum: ["default","collaborator","committer","collaboratorcommitter"]
 	TrustModel string `json:"trust_model"`
 	// ObjectFormatName of the underlying git repository, empty string for default (sha1)
-	// enum: ["sha1","sha256"]
-	ObjectFormatName string `json:"object_format_name" binding:"MaxSize(6)"`
+	ObjectFormatName ObjectFormatName `json:"object_format_name" binding:"MaxSize(6)"`
 }
 
 // EditRepoOption options when editing a repository's properties

modules/structs/repo_collaborator.go

@@ -3,17 +3,41 @@
 
 package structs
 
+// RepoWritePermission is a permission level callers may grant to a team or
+// collaborator on input. Output fields use AccessLevelName instead.
+// swagger:enum RepoWritePermission
+type RepoWritePermission string
+
+const (
+	RepoWritePermissionRead  RepoWritePermission = "read"
+	RepoWritePermissionWrite RepoWritePermission = "write"
+	RepoWritePermissionAdmin RepoWritePermission = "admin"
+)
+
+// AccessLevelName is the string rendering of a perm.AccessMode produced on
+// API responses. Callers must not send these values; use RepoWritePermission
+// on input.
+// swagger:enum AccessLevelName
+type AccessLevelName string
+
+const (
+	AccessLevelNameNone  AccessLevelName = "none"
+	AccessLevelNameRead  AccessLevelName = "read"
+	AccessLevelNameWrite AccessLevelName = "write"
+	AccessLevelNameAdmin AccessLevelName = "admin"
+	AccessLevelNameOwner AccessLevelName = "owner"
+)
+
 // AddCollaboratorOption options when adding a user as a collaborator of a repository
 type AddCollaboratorOption struct {
-	// enum: ["read","write","admin"]
 	// Permission level to grant the collaborator
-	Permission *string `json:"permission"`
+	Permission *RepoWritePermission `json:"permission"`
 }
 
 // RepoCollaboratorPermission to get repository permission for a collaborator
 type RepoCollaboratorPermission struct {
 	// Permission level of the collaborator
-	Permission string `json:"permission"`
+	Permission AccessLevelName `json:"permission"`
 	// RoleName is the name of the permission role
 	RoleName string `json:"role_name"`
 	// User information of the collaborator

modules/structs/user.go

@@ -51,7 +51,7 @@ type User struct {
 	// the user's description
 	Description string `json:"description"`
 	// User visibility level option: public, limited, private
-	Visibility string `json:"visibility"`
+	Visibility UserVisibility `json:"visibility"`
 
 	// user counts
 	Followers    int `json:"followers_count"`

modules/structs/visible_type.go

@@ -56,3 +56,14 @@ func ExtractKeysFromMapString(in map[string]VisibleType) (keys []string) {
 	}
 	return keys
 }
+
+// UserVisibility defines the visibility level of a user or organization as
+// rendered in API payloads. The DB representation is VisibleType (int).
+// swagger:enum UserVisibility
+type UserVisibility string
+
+const (
+	UserVisibilityPublic  UserVisibility = "public"
+	UserVisibilityLimited UserVisibility = "limited"
+	UserVisibilityPrivate UserVisibility = "private"
+)