Cleanup openapi generation (#4331)

Co-authored-by: oauth <woodpecker-bot@obermui.de> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: 6543 <6543@obermui.de>
2025-10-22 01:05:48 +00:00 · 2024-11-23 09:17:19 +01:00
parent 8e0aac4cab
commit 07c8765b72
26 changed files with 296 additions and 235 deletions
--- a/server/api/agent.go
+++ b/server/api/agent.go
@@ -57,7 +57,7 @@ func GetAgents(c *gin.Context) {
 //	@Success	200	{object}	Agent
 //	@Tags		Agents
 //	@Param		Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
-//	@Param		agent			path	int		true	"the agent's id"
+//	@Param		agent_id		path	int		true	"the agent's id"
 func GetAgent(c *gin.Context) {
 	agentID, err := strconv.ParseInt(c.Param("agent_id"), 10, 64)
 	if err != nil {
@@ -81,7 +81,7 @@ func GetAgent(c *gin.Context) {
 //	@Success	200	{array}	Task
 //	@Tags		Agents
 //	@Param		Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
-//	@Param		agent			path	int		true	"the agent's id"
+//	@Param		agent_id		path	int		true	"the agent's id"
 func GetAgentTasks(c *gin.Context) {
 	agentID, err := strconv.ParseInt(c.Param("agent_id"), 10, 64)
 	if err != nil {
@@ -114,7 +114,7 @@ func GetAgentTasks(c *gin.Context) {
 //	@Success	200	{object}	Agent
 //	@Tags		Agents
 //	@Param		Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
-//	@Param		agent			path	int		true	"the agent's id"
+//	@Param		agent_id		path	int		true	"the agent's id"
 //	@Param		agentData		body	Agent	true	"the agent's data"
 func PatchAgent(c *gin.Context) {
 	_store := store.FromContext(c)
@@ -156,14 +156,14 @@ func PatchAgent(c *gin.Context) {

 // PostAgent
 //
-//	@Summary	Create a new agent
-//	@Description Creates a new agent with a random token
-//	@Router		/agents [post]
-//	@Produce	json
-//	@Success	200	{object}	Agent
-//	@Tags		Agents
-//	@Param		Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
-//	@Param		agent			body	Agent	true	"the agent's data (only 'name' and 'no_schedule' are read)"
+//	@Summary		Create a new agent
+//	@Description	Creates a new agent with a random token
+//	@Router			/agents [post]
+//	@Produce		json
+//	@Success		200	{object}	Agent
+//	@Tags			Agents
+//	@Param			Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
+//	@Param			agent			body	Agent	true	"the agent's data (only 'name' and 'no_schedule' are read)"
 func PostAgent(c *gin.Context) {
 	in := &model.Agent{}
 	err := c.Bind(in)
@@ -196,7 +196,7 @@ func PostAgent(c *gin.Context) {
 //	@Success	200
 //	@Tags		Agents
 //	@Param		Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
-//	@Param		agent			path	int		true	"the agent's id"
+//	@Param		agent_id		path	int		true	"the agent's id"
 func DeleteAgent(c *gin.Context) {
 	_store := store.FromContext(c)

@@ -237,15 +237,15 @@ func DeleteAgent(c *gin.Context) {

 // PostOrgAgent
 //
-//	@Summary	Create a new organization-scoped agent
-//	@Description Creates a new agent with a random token, scoped to the specified organization
-//	@Router		/orgs/{org_id}/agents [post]
-//	@Produce	json
-//	@Success	200	{object}	Agent
-//	@Tags		Agents
-//	@Param		Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
-//	@Param		org_id			path	int		true	"the organization's id"
-//	@Param		agent			body	Agent	true	"the agent's data (only 'name' and 'no_schedule' are read)"
+//	@Summary		Create a new organization-scoped agent
+//	@Description	Creates a new agent with a random token, scoped to the specified organization
+//	@Router			/orgs/{org_id}/agents [post]
+//	@Produce		json
+//	@Success		200	{object}	Agent
+//	@Tags			Agents
+//	@Param			Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
+//	@Param			org_id			path	int		true	"the organization's id"
+//	@Param			agent			body	Agent	true	"the agent's data (only 'name' and 'no_schedule' are read)"
 func PostOrgAgent(c *gin.Context) {
 	_store := store.FromContext(c)
 	user := session.User(c)
@@ -286,7 +286,7 @@ func PostOrgAgent(c *gin.Context) {
 //	@Produce	json
 //	@Success	200	{array}	Agent
 //	@Tags		Agents
-//	@Param		Authorization	header	string	true	"Insert your personal access token"				default(Bearer <personal access token>)
+//	@Param		Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
 //	@Param		org_id			path	int		true	"the organization's id"
 //	@Param		page			query	int		false	"for response pagination, page offset number"	default(1)
 //	@Param		perPage			query	int		false	"for response pagination, max items per page"	default(50)
--- a/server/api/forge.go
+++ b/server/api/forge.go
@@ -144,14 +144,14 @@ func PatchForge(c *gin.Context) {

 // PostForge
 //
-//	@Summary	Create a new forge
-//	@Description Creates a new forge with a random token
-//	@Router		/forges [post]
-//	@Produce	json
-//	@Success	200	{object}	Forge
-//	@Tags		Forges
-//	@Param		Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
-//	@Param		forge			body	Forge	true	"the forge's data (only 'name' and 'no_schedule' are read)"
+//	@Summary		Create a new forge
+//	@Description	Creates a new forge with a random token
+//	@Router			/forges [post]
+//	@Produce		json
+//	@Success		200	{object}	Forge
+//	@Tags			Forges
+//	@Param			Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
+//	@Param			forge			body	Forge	true	"the forge's data (only 'name' and 'no_schedule' are read)"
 func PostForge(c *gin.Context) {
 	in := &model.Forge{}
 	err := c.Bind(in)
--- a/server/api/global_registry.go
+++ b/server/api/global_registry.go
@@ -32,7 +32,7 @@ import (
 //	@Success	200	{array}	Registry
 //	@Tags		Registries
 //	@Param		Authorization	header	string	true	"Insert your personal access token"				default(Bearer <personal access token>)
-//	@Param		page				query	int		false	"for response pagination, page offset number"	default(1)
+//	@Param		page			query	int		false	"for response pagination, page offset number"	default(1)
 //	@Param		perPage			query	int		false	"for response pagination, max items per page"	default(50)
 func GetGlobalRegistryList(c *gin.Context) {
 	registryService := server.Config.Services.Manager.RegistryService()
@@ -57,7 +57,7 @@ func GetGlobalRegistryList(c *gin.Context) {
 //	@Success	200	{object}	Registry
 //	@Tags		Registries
 //	@Param		Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
-//	@Param		registry			path	string	true	"the registry's name"
+//	@Param		registry		path	string	true	"the registry's name"
 func GetGlobalRegistry(c *gin.Context) {
 	addr := c.Param("registry")
 	registryService := server.Config.Services.Manager.RegistryService()
@@ -76,8 +76,8 @@ func GetGlobalRegistry(c *gin.Context) {
 //	@Produce	json
 //	@Success	200	{object}	Registry
 //	@Tags		Registries
-//	@Param		Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
-//	@Param		registry			body	Registry	true	"the registry object data"
+//	@Param		Authorization	header	string		true	"Insert your personal access token"	default(Bearer <personal access token>)
+//	@Param		registry		body	Registry	true	"the registry object data"
 func PostGlobalRegistry(c *gin.Context) {
 	in := new(model.Registry)
 	if err := c.Bind(in); err != nil {
@@ -109,8 +109,8 @@ func PostGlobalRegistry(c *gin.Context) {
 //	@Produce	json
 //	@Success	200	{object}	Registry
 //	@Tags		Registries
-//	@Param		Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
-//	@Param		registry			path	string		true	"the registry's name"
+//	@Param		Authorization	header	string		true	"Insert your personal access token"	default(Bearer <personal access token>)
+//	@Param		registry		path	string		true	"the registry's name"
 //	@Param		registryData	body	Registry	true	"the registry's data"
 func PatchGlobalRegistry(c *gin.Context) {
 	addr := c.Param("registry")
@@ -158,7 +158,7 @@ func PatchGlobalRegistry(c *gin.Context) {
 //	@Success	204
 //	@Tags		Registries
 //	@Param		Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
-//	@Param		registry			path		string	true	"the registry's name"
+//	@Param		registry		path	string	true	"the registry's name"
 func DeleteGlobalRegistry(c *gin.Context) {
 	addr := c.Param("registry")
 	registryService := server.Config.Services.Manager.RegistryService()
--- a/server/api/org_registry.go
+++ b/server/api/org_registry.go
@@ -56,8 +56,8 @@ func GetOrgRegistry(c *gin.Context) {
 //	@Tags		Organization registries
 //	@Param		Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
 //	@Param		org_id			path	string	true	"the org's id"
-//	@Param		page				query	int			false	"for response pagination, page offset number"	default(1)
-//	@Param		perPage			query	int			false	"for response pagination, max items per page"	default(50)
+//	@Param		page			query	int		false	"for response pagination, page offset number"	default(1)
+//	@Param		perPage			query	int		false	"for response pagination, max items per page"	default(50)
 func GetOrgRegistryList(c *gin.Context) {
 	org := session.Org(c)

@@ -83,8 +83,8 @@ func GetOrgRegistryList(c *gin.Context) {
 //	@Success	200	{object}	Registry
 //	@Tags		Organization registries
 //	@Param		Authorization	header	string		true	"Insert your personal access token"	default(Bearer <personal access token>)
-//	@Param		org_id					path	string		true	"the org's id"
-//	@Param		registryData		body	Registry	true	"the new registry"
+//	@Param		org_id			path	string		true	"the org's id"
+//	@Param		registryData	body	Registry	true	"the new registry"
 func PostOrgRegistry(c *gin.Context) {
 	org := session.Org(c)

@@ -119,9 +119,9 @@ func PostOrgRegistry(c *gin.Context) {
 //	@Produce	json
 //	@Success	200	{object}	Registry
 //	@Tags		Organization registries
-//	@Param		Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
-//	@Param		org_id				path	string		true	"the org's id"
-//	@Param		registry			path	string		true	"the registry's name"
+//	@Param		Authorization	header	string		true	"Insert your personal access token"	default(Bearer <personal access token>)
+//	@Param		org_id			path	string		true	"the org's id"
+//	@Param		registry		path	string		true	"the registry's name"
 //	@Param		registryData	body	Registry	true	"the update registry data"
 func PatchOrgRegistry(c *gin.Context) {
 	org := session.Org(c)
--- a/server/api/pipeline.go
+++ b/server/api/pipeline.go
@@ -104,18 +104,18 @@ func createTmpPipeline(event model.WebhookEvent, commit *model.Commit, user *mod

 // GetPipelines
 //
-//	@Summary	List repository pipelines
+//	@Summary		List repository pipelines
 //	@Description	Get a list of pipelines for a repository.
-//	@Router		/repos/{repo_id}/pipelines [get]
-//	@Produce	json
-//	@Success	200	{array}	Pipeline
-//	@Tags		Pipelines
-//	@Param		Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
-//	@Param		repo_id			path	int		true	"the repository id"
-//	@Param		page			query	int		false	"for response pagination, page offset number"	default(1)
-//	@Param		perPage			query	int		false	"for response pagination, max items per page"	default(50)
-//	@Param		before			query	string	false	"only return pipelines before this RFC3339 date"
-//	@Param		after			query	string	false	"only return pipelines after this RFC3339 date"
+//	@Router			/repos/{repo_id}/pipelines [get]
+//	@Produce		json
+//	@Success		200	{array}	Pipeline
+//	@Tags			Pipelines
+//	@Param			Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
+//	@Param			repo_id			path	int		true	"the repository id"
+//	@Param			page			query	int		false	"for response pagination, page offset number"	default(1)
+//	@Param			perPage			query	int		false	"for response pagination, max items per page"	default(50)
+//	@Param			before			query	string	false	"only return pipelines before this RFC3339 date"
+//	@Param			after			query	string	false	"only return pipelines after this RFC3339 date"
 func GetPipelines(c *gin.Context) {
 	repo := session.Repo(c)
 	before := c.Query("before")
--- a/server/api/repo.go
+++ b/server/api/repo.go
@@ -591,16 +591,16 @@ func MoveRepo(c *gin.Context) {

 // GetAllRepos
 //
-//	@Summary	List all repositories on the server
+//	@Summary		List all repositories on the server
 //	@Description	Returns a list of all repositories. Requires admin rights.
-//	@Router		/repos [get]
-//	@Produce	json
-//	@Success	200	{array}	Repo
-//	@Tags		Repositories
-//	@Param		Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
-//	@Param		active			query	bool	false	"only list active repos"
-//	@Param		page			query	int		false	"for response pagination, page offset number"	default(1)
-//	@Param		perPage			query	int		false	"for response pagination, max items per page"	default(50)
+//	@Router			/repos [get]
+//	@Produce		json
+//	@Success		200	{array}	Repo
+//	@Tags			Repositories
+//	@Param			Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
+//	@Param			active			query	bool	false	"only list active repos"
+//	@Param			page			query	int		false	"for response pagination, page offset number"	default(1)
+//	@Param			perPage			query	int		false	"for response pagination, max items per page"	default(50)
 func GetAllRepos(c *gin.Context) {
 	_store := store.FromContext(c)

@@ -617,13 +617,13 @@ func GetAllRepos(c *gin.Context) {

 // RepairAllRepos
 //
-//	@Summary	Repair all repositories on the server
-//	@Description Executes a repair process on all repositories. Requires admin rights.
-//	@Router		/repos/repair [post]
-//	@Produce	plain
-//	@Success	204
-//	@Tags		Repositories
-//	@Param		Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
+//	@Summary		Repair all repositories on the server
+//	@Description	Executes a repair process on all repositories. Requires admin rights.
+//	@Router			/repos/repair [post]
+//	@Produce		plain
+//	@Success		204
+//	@Tags			Repositories
+//	@Param			Authorization	header	string	true	"Insert your personal access token"	default(Bearer <personal access token>)
 func RepairAllRepos(c *gin.Context) {
 	_store := store.FromContext(c)

--- a/server/api/z.go
+++ b/server/api/z.go
@@ -48,7 +48,7 @@ func Health(c *gin.Context) {
 //	@Description	Endpoint returns the server version and build information.
 //	@Router			/version [get]
 //	@Produce		json
-//	@Success		200	{object}	string{source=string,version=string}
+//	@Success		200	{object}	object{source=string,version=string}
 //	@Tags			System
 func Version(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{
--- a/server/router/router.go
+++ b/server/router/router.go
@@ -20,10 +20,10 @@ import (

 	"github.com/gin-gonic/gin"
 	"github.com/rs/zerolog/log"
-	swagger_files "github.com/swaggo/files"
+	openapi_files "github.com/swaggo/files"
 	ginSwagger "github.com/swaggo/gin-swagger"

-	"go.woodpecker-ci.org/woodpecker/v2/cmd/server/docs"
+	"go.woodpecker-ci.org/woodpecker/v2/cmd/server/openapi"
 	"go.woodpecker-ci.org/woodpecker/v2/server"
 	"go.woodpecker-ci.org/woodpecker/v2/server/api"
 	"go.woodpecker-ci.org/woodpecker/v2/server/api/metrics"
@@ -78,9 +78,9 @@ func Load(noRouteHandler http.HandlerFunc, middleware ...gin.HandlerFunc) http.H
 }

 func setupSwaggerConfigAndRoutes(e *gin.Engine) {
-	docs.SwaggerInfo.Host = getHost(server.Config.Server.Host)
-	docs.SwaggerInfo.BasePath = server.Config.Server.RootPath + "/api"
-	e.GET(server.Config.Server.RootPath+"/swagger/*any", ginSwagger.WrapHandler(swagger_files.Handler))
+	openapi.SwaggerInfo.Host = getHost(server.Config.Server.Host)
+	openapi.SwaggerInfo.BasePath = server.Config.Server.RootPath + "/api"
+	e.GET(server.Config.Server.RootPath+"/swagger/*any", ginSwagger.WrapHandler(openapi_files.Handler))
 }

 func getHost(s string) string {