modify swagger

nilorg · Nov 26, 2020 · d3bda48 · d3bda48
1 parent 896af22
commit d3bda48
Show file tree

Hide file tree

Showing 10 changed files with 2,867 additions and 296 deletions.
diff --git a/docs/docs.go b/docs/docs.go
diff --git a/docs/swagger.json b/docs/swagger.json
diff --git a/docs/swagger.yaml b/docs/swagger.yaml
diff --git a/internal/controller/api/casbin.go b/internal/controller/api/casbin.go
@@ -10,6 +10,15 @@ import (
 type casbin struct {
 }
 
+// GetScopeOne 获取资源服务器Web路由
+// @Tags 		Casbin
+// @Summary		获取资源服务器Web路由翻页列表
+// @Accept  json
+// @Produce	json
+// @Param 	resource_server_id	path	string	true	"resource server id"
+// @Success 200	{object}	Result{data=model.TableListData}
+// @Router /casbin/resource/{resource_server_id}/web_routes [GET]
+// @Security OAuth2AccessCode
 func (*casbin) ListResourceWebRoutes(ctx *gin.Context) {
 	var (
 		list []*model.ResourceWebRoute
@@ -24,6 +33,17 @@ func (*casbin) ListResourceWebRoutes(ctx *gin.Context) {
 	}
 	writeData(ctx, model.NewTableListData(*pagination, list))
 }
+
+// GetScopeOne 根据角色获取资源服务器Web路由
+// @Tags 		Casbin
+// @Summary		根据角色获取资源服务器Web路由翻页列表
+// @Accept  json
+// @Produce	json
+// @Param 	role_code	path	string	true	"role code"
+// @Param 	resource_server_id	path	string	true	"resource server id"
+// @Success 200	{object}	Result{data=model.TableListData}
+// @Router /casbin/role/{role_code}/resource/{resource_server_id}/web_routes [GET]
+// @Security OAuth2AccessCode
 func (*casbin) ListRoleResourceWebRoutes(ctx *gin.Context) {
 	var (
 		list []*model.RoleResourceRelation
@@ -46,7 +66,7 @@ func (*casbin) ListRoleResourceWebRoutes(ctx *gin.Context) {
 // @Produce	json
 // @Param	role_code		path	string	true	"角色Code"
 // @Success 200	{object}	Result
-// @Router /casbin/role/:role_code/resource_web_routes [POST]
+// @Router /casbin/role/{role_code}/resource_web_routes [PUT]
 // @Security OAuth2AccessCode
 func (*casbin) AddResourceWebRoute(ctx *gin.Context) {
 	roleCode := ctx.Param("role_code")
@@ -74,7 +94,7 @@ func (*casbin) AddResourceWebRoute(ctx *gin.Context) {
 // @Produce	json
 // @Param	role_code		path	string	true	"角色Code"
 // @Success 200	{object}	Result
-// @Router /casbin/role/:role_code/resource_web_menus [POST]
+// @Router /casbin/role/{role_code}/resource_web_menus [PUT]
 // @Security OAuth2AccessCode
 func (*casbin) AddResourceWebMenu(ctx *gin.Context) {
 	roleCode := ctx.Param("role_code")
@@ -95,6 +115,15 @@ func (*casbin) AddResourceWebMenu(ctx *gin.Context) {
 	writeData(ctx, nil)
 }
 
+// GetScopeOne 获取资源服务器Web菜单
+// @Tags 		Casbin
+// @Summary		获取资源服务器Web菜单翻页列表
+// @Accept  json
+// @Produce	json
+// @Param 	resource_server_id	path	string	true	"resource server id"
+// @Success 200	{object}	Result{data=model.TableListData}
+// @Router /casbin/resource/{resource_server_id}/web_menus [GET]
+// @Security OAuth2AccessCode
 func (*casbin) ListResourceWebMenus(ctx *gin.Context) {
 	var (
 		list []*model.ResourceWebMenu
@@ -110,6 +139,16 @@ func (*casbin) ListResourceWebMenus(ctx *gin.Context) {
 	writeData(ctx, model.NewTableListData(*pagination, list))
 }
 
+// GetScopeOne 根据角色获取资源服务器Web菜单
+// @Tags 		Casbin
+// @Summary		根据角色获取资源服务器Web菜单翻页列表
+// @Accept  json
+// @Produce	json
+// @Param 	role_code	path	string	true	"role code"
+// @Param 	resource_server_id	path	string	true	"resource server id"
+// @Success 200	{object}	Result{data=model.TableListData}
+// @Router /casbin/role/{role_code}/resource/{resource_server_id}/web_menus [GET]
+// @Security OAuth2AccessCode
 func (*casbin) ListRoleResourceWebMenus(ctx *gin.Context) {
 	var (
 		list []*model.RoleResourceRelation

diff --git a/internal/controller/api/common.go b/internal/controller/api/common.go
@@ -16,11 +16,13 @@ type common struct {
 // SelectQueryChildren 查询方法
 // @Tags 		Common（通用）
 // @Summary		查询角色
-// @Description	org:组织
-// @Description	xxxx:其他
+// @Description	organization:组织
+// @Description	resource_server:资源服务器
+// @Description	role:角色
+// @Description	oauth2_scope:OAuth2Scope
 // @Accept  json
 // @Produce	json
-// @Param q query string true "查询参数" Enums(org,xxxx)
+// @Param q query string true "查询参数" Enums(organization,resource_server,role,oauth2_scope)
 // @Param pageSize query int true "页大小"
 // @Success 200	{object}	Result{data=model.ResultSelect}
 // @Router /common/select [GET]
@@ -38,10 +40,9 @@ func (c *common) SelectQueryChildren() gin.HandlerFunc {
 // @Tags 		Common（通用）
 // @Summary		查询角色
 // @Description	resource_web_menu:web菜单
-// @Description	xxxx:其他
 // @Accept  json
 // @Produce	json
-// @Param q query string true "查询参数" Enums(resource_web_menu,xxxx)
+// @Param q query string true "查询参数" Enums(resource_web_menu)
 // @Param pageSize query int true "页大小"
 // @Success 200	{object}	Result{data=model.ResultSelect}
 // @Router /common/tree [GET]

diff --git a/internal/controller/api/file.go b/internal/controller/api/file.go
@@ -16,6 +16,15 @@ import (
 type file struct {
 }
 
+// Upload 文件上传
+// @Tags 		文件
+// @Summary		文件上传
+// @Accept multipart/form-data
+// @Produce	json
+// @Param file formData file true "upload file"
+// @Success 200	{object}	Result
+// @Router /files [POST]
+// @Security OAuth2AccessCode
 func (*file) Upload(ctx *gin.Context) {
 	var (
 		finfos []storage.UploadFileInfoer

diff --git a/internal/controller/api/organization.go b/internal/controller/api/organization.go
@@ -18,9 +18,9 @@ type organization struct {
 // @Description	根据组织ID,获取一个组织
 // @Accept  json
 // @Produce	json
-// @Param 	org_id	path	string	true	"org id"
+// @Param 	organization_id	path	string	true	"org id"
 // @Success 200	{object}	Result
-// @Router /organizations/{org_id} [GET]
+// @Router /organizations/{organization_id} [GET]
 // @Security OAuth2AccessCode
 func (*organization) GetOne(ctx *gin.Context) {
 	var (
@@ -70,15 +70,15 @@ func (*organization) Create(ctx *gin.Context) {
 // @Description	根据组织ID,删除一个组织
 // @Accept  json
 // @Produce	json
-// @Param 	org_id	path	string	true	"organization id"
+// @Param 	organization_id	path	string	true	"organization id"
 // @Success 200	{object}	Result
-// @Router /organizations/{org_id} [DELETE]
+// @Router /organizations/{organization_id} [DELETE]
 // @Security OAuth2AccessCode
 func (*organization) Delete(ctx *gin.Context) {
 	var (
 		err error
 	)
-	idsStringSplit := strings.Split(ctx.Param("org_id"), ",")
+	idsStringSplit := strings.Split(ctx.Param("organization_id"), ",")
 	var idsUint64Split []model.ID
 	for _, id := range idsStringSplit {
 		idsUint64Split = append(idsUint64Split, model.ConvertStringToID(id))
@@ -97,17 +97,17 @@ func (*organization) Delete(ctx *gin.Context) {
 // @Description	根据组织ID,修改一个组织
 // @Accept  json
 // @Produce	json
-// @Param 	org_id	path	string	true	"organization id"
+// @Param 	organization_id	path	string	true	"organization id"
 // @Param 	body	body	service.OrganizationEditModel	true	"组织需要修改的信息"
 // @Success 200	{object}	Result
-// @Router /organizations/{org_id} [PUT]
+// @Router /organizations/{organization_id} [PUT]
 // @Security OAuth2AccessCode
 func (*organization) Update(ctx *gin.Context) {
 	var (
 		org service.OrganizationEditModel
 		err error
 	)
-	orgID := model.ConvertStringToID(ctx.Param("org_id"))
+	orgID := model.ConvertStringToID(ctx.Param("organization_id"))
 	err = ctx.ShouldBindJSON(&org)
 	if err != nil {
 		writeError(ctx, err)

diff --git a/internal/controller/api/resource.go b/internal/controller/api/resource.go
@@ -173,7 +173,7 @@ func (*resource) AddWebRoute(ctx *gin.Context) {
 // @Param 	resource_web_route_id	path	string	true	"resource web route id"
 // @Param 	body	body	service.ResourceWebRouteEdit	true	"Web路由需要修改的信息"
 // @Success 200	{object}	Result
-// @Router /resource/web_routes/:resource_web_route_id [PUT]
+// @Router /resource/web_routes/{resource_web_route_id} [PUT]
 // @Security OAuth2AccessCode
 func (*resource) UpdateWebRoute(ctx *gin.Context) {
 	var (
@@ -298,7 +298,7 @@ func (*resource) AddWebMenu(ctx *gin.Context) {
 // @Param 	resource_web_menu_id	path	string	true	"resource web menu id"
 // @Param 	body	body	service.ResourceWebMenuEdit	true	"Web路由需要修改的信息"
 // @Success 200	{object}	Result
-// @Router /resource/web_routes/:resource_web_menu_id [PUT]
+// @Router /resource/web_routes/{resource_web_menu_id} [PUT]
 // @Security OAuth2AccessCode
 func (*resource) UpdateWebMenu(ctx *gin.Context) {
 	var (

diff --git a/internal/controller/api/role.go b/internal/controller/api/role.go
@@ -16,9 +16,11 @@ type role struct {
 // @Summary		查询角色
 // @Description	recursive:递归获取所有角色
 // @Description	list:查询列表
+// @Description	tree_select:选择列表
+// @Description	tree_node:选择列表节点
 // @Accept  json
 // @Produce	json
-// @Param q query string true "查询参数" Enums(recursive,list)
+// @Param q query string true "查询参数" Enums(recursive,list,tree_select,tree_node)
 // @Success 200	{object}	Result{data=model.TableListData}
 // @Success 200	{object}	Result{data=[]model.Role}
 // @Router /roles [GET]

diff --git a/internal/server/server.go b/internal/server/server.go
@@ -195,18 +195,17 @@ func RunHTTP() {
 			apiGroup.PUT("/oauth2/scopes/:scop_code", api.OAuth2.EditScope)
 
 			apiGroup.GET("/organizations", api.Organization.QueryChildren())
-			apiGroup.GET("/organizations/:org_id", api.Organization.GetOne)
+			apiGroup.GET("/organizations/:organization_id", api.Organization.GetOne)
 			apiGroup.POST("/organizations", api.Organization.Create)
-			apiGroup.PUT("/organizations/:org_id", api.Organization.Update)
-			apiGroup.DELETE("/organizations/:org_id", api.Organization.Delete)
+			apiGroup.PUT("/organizations/:organization_id", api.Organization.Update)
+			apiGroup.DELETE("/organizations/:organization_id", api.Organization.Delete)
 
 			apiGroup.GET("/casbin/resource/:resource_server_id/web_routes", api.Casbin.ListResourceWebRoutes)
 			apiGroup.GET("/casbin/role/:role_code/resource/:resource_server_id/web_routes", api.Casbin.ListRoleResourceWebRoutes)
 			apiGroup.PUT("/casbin/role/:role_code/resource_web_routes", api.Casbin.AddResourceWebRoute)
 
 			apiGroup.GET("/casbin/resource/:resource_server_id/web_menus", api.Casbin.ListResourceWebMenus)
 			apiGroup.GET("/casbin/role/:role_code/resource/:resource_server_id/web_menus", api.Casbin.ListRoleResourceWebMenus)
-
 			apiGroup.PUT("/casbin/role/:role_code/resource_web_menus", api.Casbin.AddResourceWebMenu)
 
 			apiGroup.GET("/common/select", api.Common.SelectQueryChildren())