add swag doc info

Signed-off-by: Patrick Zhao <zhaoyu@koderover.com>
koderover · Nov 13, 2024 · 10ba93a · 10ba93a
1 parent db9c98d
commit 10ba93a
Show file tree

Hide file tree

Showing 10 changed files with 115 additions and 0 deletions.
diff --git a/.gitignore b/.gitignore
@@ -40,6 +40,7 @@ godoc-proxy/website/dist
 
 #Swagger info
 pkg/microservice/aslan/server/rest/doc
+pkg/microservice/user/server/rest/doc
 
 npm-debug.log
 .bowerrc

diff --git a/Makefile b/Makefile
@@ -42,6 +42,8 @@ debugtools: prereq $(DEBUG_TOOLS_TARGETS:=.push)
 
 swag:
 	swag init --parseDependency --parseInternal --parseDepth 1 -d cmd/aslan,pkg/microservice/aslan -g ../../pkg/microservice/aslan/server/rest/router.go -o pkg/microservice/aslan/server/rest/doc
+swag-user:
+	swag init --parseDependency --parseInternal --parseDepth 1 -d cmd/aslan,pkg/microservice/user -g ../../pkg/microservice/user/server/rest/router.go -o pkg/microservice/user/server/rest/doc
 
 # zadig-agent
 # Usage:

diff --git a/pkg/microservice/aslan/core/build/handler/build.go b/pkg/microservice/aslan/core/build/handler/build.go
@@ -32,6 +32,15 @@ import (
 	"github.com/koderover/zadig/v2/pkg/tool/log"
 )
 
+// @Summary 获取构建详情
+// @Description
+// @Tags 	build
+// @Accept 	json
+// @Produce json
+// @Param 	projectKey		query		string							true	"项目标识"
+// @Param 	name			path		string							true	"构建标识"
+// @Success 200 			{object} 	commonmodels.Build
+// @Router /api/aslan/build/build/{name} [get]
 func FindBuildModule(c *gin.Context) {
 	ctx, err := internalhandler.NewContextWithAuthorization(c)
 	defer func() { internalhandler.JSONResponse(c, ctx) }()
@@ -202,6 +211,14 @@ func CreateBuildModule(c *gin.Context) {
 	ctx.RespErr = buildservice.CreateBuild(ctx.UserName, args, ctx.Logger)
 }
 
+// @Summary 更新构建
+// @Description 如果仅需要更新服务和代码信息，则只需要更新target_repos字段
+// @Tags 	build
+// @Accept 	json
+// @Produce json
+// @Param 	body 			body 		commonmodels.Build		  true 	"body"
+// @Success 200
+// @Router /api/aslan/build/build [put]
 func UpdateBuildModule(c *gin.Context) {
 	ctx, err := internalhandler.NewContextWithAuthorization(c)
 	defer func() { internalhandler.JSONResponse(c, ctx) }()

diff --git a/pkg/microservice/aslan/core/service/handler/service.go b/pkg/microservice/aslan/core/service/handler/service.go
@@ -1032,6 +1032,14 @@ type addServiceLabelReq struct {
 	Value       string `json:"value,omitempty"`
 }
 
+// @Summary 服务添加标签
+// @Description 全部参数都是必传
+// @Tags 	service
+// @Accept 	json
+// @Produce json
+// @Param 	body 			body 		addServiceLabelReq 	  true 	"body"
+// @Success 200
+// @Router /api/aslan/service/labels [post]
 func AddServiceLabel(c *gin.Context) {
 	ctx, err := internalhandler.NewContextWithAuthorization(c)
 	defer func() { internalhandler.JSONResponse(c, ctx) }()
@@ -1281,6 +1289,16 @@ type listServiceLabelReq struct {
 	Production  string `json:"production,omitempty" form:"production,omitempty"`
 }
 
+// @Summary 获取服务的标签列表
+// @Description
+// @Tags 	service
+// @Accept 	json
+// @Produce json
+// @Param 	projectKey		query		string							true	"项目标识"
+// @Param 	serviceName		query		string							true	"服务名称"
+// @Param 	production		query		string							true	"是否为生产服务，true:生产服务，false:非生产服务"
+// @Success 200 			{object} 	svcservice.ServiceLabelResp
+// @Router /api/aslan/service/labels [get]
 func ListServiceLabels(c *gin.Context) {
 	ctx, err := internalhandler.NewContextWithAuthorization(c)
 	defer func() { internalhandler.JSONResponse(c, ctx) }()

diff --git a/pkg/microservice/aslan/core/system/handler/labels.go b/pkg/microservice/aslan/core/system/handler/labels.go
@@ -27,6 +27,14 @@ import (
 	e "github.com/koderover/zadig/v2/pkg/tool/errors"
 )
 
+// @Summary 创建服务标签
+// @Description 只需要传入参数key
+// @Tags 	system
+// @Accept 	json
+// @Produce json
+// @Param 	body 			body 		commonmodels.Label 	  true 	"body"
+// @Success 200
+// @Router /api/aslan/system/labels [post]
 func CreateServiceLabelSetting(c *gin.Context) {
 	ctx, err := internalhandler.NewContextWithAuthorization(c)
 	defer func() { internalhandler.JSONResponse(c, ctx) }()
@@ -54,6 +62,13 @@ func CreateServiceLabelSetting(c *gin.Context) {
 	ctx.RespErr = service.CreateServiceLabelSetting(args, ctx.Logger)
 }
 
+// @Summary 获取服务标签配置列表
+// @Description
+// @Tags 	system
+// @Accept 	json
+// @Produce json
+// @Success 200 			{array} 	commonmodels.Label
+// @Router /api/aslan/system/labels [get]
 func ListServiceLabelSettings(c *gin.Context) {
 	ctx := internalhandler.NewContext(c)
 	defer func() { internalhandler.JSONResponse(c, ctx) }()

diff --git a/pkg/microservice/aslan/core/templatestore/handler/scanning.go b/pkg/microservice/aslan/core/templatestore/handler/scanning.go
@@ -28,6 +28,14 @@ import (
 	e "github.com/koderover/zadig/v2/pkg/tool/errors"
 )
 
+// @Summary 获取代码扫描模版
+// @Description
+// @Tags 	template
+// @Accept 	json
+// @Produce json
+// @Param 	id			path		string								true	"代码扫描模版ID"
+// @Success 200  		{object} 	commonmodels.ScanningTemplate
+// @Router /api/aslan/template/scanning/{id} [get]
 func GetScanningTemplate(c *gin.Context) {
 	ctx, err := internalhandler.NewContextWithAuthorization(c)
 	defer func() { internalhandler.JSONResponse(c, ctx) }()

diff --git a/pkg/microservice/aslan/core/workflow/handler/workflow_v4.go b/pkg/microservice/aslan/core/workflow/handler/workflow_v4.go
@@ -72,6 +72,16 @@ type listWorkflowV4Resp struct {
 	Total        int64                `json:"total"`
 }
 
+// @Summary 创建工作流
+// @Description 创建工作流
+// @Tags 	workflow
+// @Accept 	plain
+// @Produce json
+// @Param 	projectName		query		string								true	"项目标识"
+// @Param 	viewName 		query		string								true	"需要添加的视图名称"
+// @Param 	body 			body 		commonmodels.WorkflowV4 			true 	"工作流Yaml"
+// @Success 200
+// @Router /api/aslan/workflow/v4 [post]
 func CreateWorkflowV4(c *gin.Context) {
 	ctx, err := internalhandler.NewContextWithAuthorization(c)
 	defer func() { internalhandler.JSONResponse(c, ctx) }()
@@ -274,6 +284,16 @@ func ListWorkflowV4CanTrigger(c *gin.Context) {
 	ctx.Resp, ctx.RespErr = workflow.ListWorkflowV4CanTrigger(ctx)
 }
 
+// @Summary 更新工作流
+// @Description 更新工作流
+// @Tags 	workflow
+// @Accept 	plain
+// @Produce json
+// @Param 	projectName		query		string								true	"项目标识"
+// @Param 	name			path		string								true	"工作流标识"
+// @Param 	body 			body 		commonmodels.WorkflowV4 			true 	"工作流Yaml"
+// @Success 200
+// @Router /api/aslan/workflow/v4/{name} [put]
 func UpdateWorkflowV4(c *gin.Context) {
 	ctx, err := internalhandler.NewContextWithAuthorization(c)
 	defer func() { internalhandler.JSONResponse(c, ctx) }()

diff --git a/pkg/microservice/aslan/core/workflow/testing/handler/scanning.go b/pkg/microservice/aslan/core/workflow/testing/handler/scanning.go
@@ -76,6 +76,15 @@ func FindScanningProjectNameFromID(c *gin.Context) {
 	c.Next()
 }
 
+// @Summary 创建代码扫描
+// @Description 使用模版创建时，template_id为必传
+// @Tags 	testing
+// @Accept 	json
+// @Produce json
+// @Param 	projectName 	query		string								true	"项目标识"
+// @Param 	body 			body 		service.Scanning 					true 	"body"
+// @Success 200
+// @Router /api/aslan/testing/scanning [post]
 func CreateScanningModule(c *gin.Context) {
 	ctx, err := internalhandler.NewContextWithAuthorization(c)
 	defer func() { internalhandler.JSONResponse(c, ctx) }()

diff --git a/pkg/microservice/user/core/handler/user/user.go b/pkg/microservice/user/core/handler/user/user.go
@@ -137,6 +137,14 @@ func GetUserSetting(c *gin.Context) {
 	ctx.Resp, ctx.RespErr = permission.GetUserSetting(uid, ctx.Logger)
 }
 
+// @Summary 获取用户列表
+// @Description 获取用户列表只需要传page和per_page参数，搜索时需要再加上name参数
+// @Tags 	user
+// @Accept 	json
+// @Produce json
+// @Param 	body 		body 		permission.QueryArgs 	  true 	"body"
+// @Success 200 		{object} 	types.UsersResp
+// @Router /api/v1/users/search [post]
 func ListUsers(c *gin.Context) {
 	ctx := internalhandler.NewContext(c)
 	defer func() { internalhandler.JSONResponse(c, ctx) }()

diff --git a/pkg/microservice/user/core/handler/user/user_group.go b/pkg/microservice/user/core/handler/user/user_group.go
@@ -32,6 +32,14 @@ type createUserGroupReq struct {
 	UIDs        []string `json:"uids"`
 }
 
+// @Summary 创建用户组
+// @Description 创建用户组
+// @Tags 	user
+// @Accept 	json
+// @Produce json
+// @Param 	body 			body 		createUserGroupReq 	true 	"body"
+// @Success 200
+// @Router /api/v1/user-group [post]
 func CreateUserGroup(c *gin.Context) {
 	ctx := internalhandler.NewContext(c)
 	defer func() { internalhandler.JSONResponse(c, ctx) }()
@@ -260,6 +268,15 @@ type bulkUserReq struct {
 	UIDs []string `json:"uids"`
 }
 
+// @Summary 添加用户到用户组
+// @Description 添加用户到用户组
+// @Tags 	user
+// @Accept 	json
+// @Produce json
+// @Param 	id 				path 		string 			true 	"用户组ID"
+// @Param 	body 			body 		bulkUserReq 	true 	"body"
+// @Success 200
+// @Router /api/v1/user-group/{id}/bulk-create-users [post]
 func BulkAddUserToUserGroup(c *gin.Context) {
 	ctx := internalhandler.NewContext(c)
 	defer func() { internalhandler.JSONResponse(c, ctx) }()