fix: kusion server handler swagger apis (#1365)

* fix: kusion server swagger apis * chore: update handler query parameters * chore: update module handler query parameter Co-authored-by: Yang Yang <yy5478@hotmail.com> * chore: update module handler api query * chore: update swagger api docs --------- Co-authored-by: Yang Yang <yy5478@hotmail.com>
KusionStack · Dec 30, 2024 · 8dd0b1b · 8dd0b1b
1 parent d3115e3
commit 8dd0b1b
Show file tree

Hide file tree

Showing 16 changed files with 494 additions and 473 deletions.
diff --git a/api/openapispec/docs.go b/api/openapispec/docs.go
diff --git a/api/openapispec/swagger.json b/api/openapispec/swagger.json
diff --git a/api/openapispec/swagger.yaml b/api/openapispec/swagger.yaml
diff --git a/go.mod b/go.mod
@@ -260,7 +260,7 @@ require (
 	github.com/jinzhu/now v1.1.5 // indirect
 	github.com/jmespath/go-jmespath v0.4.0 // indirect
 	github.com/josharian/intern v1.0.0 // indirect
-	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/json-iterator/go v1.1.12
 	github.com/jtolds/gls v4.20.0+incompatible // indirect
 	github.com/julienschmidt/httprouter v1.3.0 // indirect
 	github.com/kevinburke/ssh_config v1.2.0 // indirect

diff --git a/pkg/server/handler/backend/handler.go b/pkg/server/handler/backend/handler.go
@@ -53,14 +53,14 @@ func (h *Handler) CreateBackend() http.HandlerFunc {
 // @Description	Delete specified backend by ID
 // @Tags			backend
 // @Produce		json
-// @Param			id	path		int								true	"Backend ID"
-// @Success		200	{object}	handler.Response{data=string}	"Success"
-// @Failure		400	{object}	error							"Bad Request"
-// @Failure		401	{object}	error							"Unauthorized"
-// @Failure		429	{object}	error							"Too Many Requests"
-// @Failure		404	{object}	error							"Not Found"
-// @Failure		500	{object}	error							"Internal Server Error"
-// @Router			/api/v1/backends/{id} [delete]
+// @Param			backendID	path		int								true	"Backend ID"
+// @Success		200			{object}	handler.Response{data=string}	"Success"
+// @Failure		400			{object}	error							"Bad Request"
+// @Failure		401			{object}	error							"Unauthorized"
+// @Failure		429			{object}	error							"Too Many Requests"
+// @Failure		404			{object}	error							"Not Found"
+// @Failure		500			{object}	error							"Internal Server Error"
+// @Router			/api/v1/backends/{backendID} [delete]
 func (h *Handler) DeleteBackend() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		// Getting stuff from context
@@ -82,15 +82,15 @@ func (h *Handler) DeleteBackend() http.HandlerFunc {
 // @Tags			backend
 // @Accept			json
 // @Produce		json
-// @Param			id		path		int										true	"Backend ID"
-// @Param			backend	body		request.UpdateBackendRequest			true	"Updated backend"
-// @Success		200		{object}	handler.Response{data=entity.Backend}	"Success"
-// @Failure		400		{object}	error									"Bad Request"
-// @Failure		401		{object}	error									"Unauthorized"
-// @Failure		429		{object}	error									"Too Many Requests"
-// @Failure		404		{object}	error									"Not Found"
-// @Failure		500		{object}	error									"Internal Server Error"
-// @Router			/api/v1/backends/{id} [put]
+// @Param			backendID	path		int										true	"Backend ID"
+// @Param			backend		body		request.UpdateBackendRequest			true	"Updated backend"
+// @Success		200			{object}	handler.Response{data=entity.Backend}	"Success"
+// @Failure		400			{object}	error									"Bad Request"
+// @Failure		401			{object}	error									"Unauthorized"
+// @Failure		429			{object}	error									"Too Many Requests"
+// @Failure		404			{object}	error									"Not Found"
+// @Failure		500			{object}	error									"Internal Server Error"
+// @Router			/api/v1/backends/{backendID} [put]
 func (h *Handler) UpdateBackend() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		// Getting stuff from context
@@ -118,14 +118,14 @@ func (h *Handler) UpdateBackend() http.HandlerFunc {
 // @Description	Get backend information by backend ID
 // @Tags			backend
 // @Produce		json
-// @Param			id	path		int										true	"Backend ID"
-// @Success		200	{object}	handler.Response{data=entity.Backend}	"Success"
-// @Failure		400	{object}	error									"Bad Request"
-// @Failure		401	{object}	error									"Unauthorized"
-// @Failure		429	{object}	error									"Too Many Requests"
-// @Failure		404	{object}	error									"Not Found"
-// @Failure		500	{object}	error									"Internal Server Error"
-// @Router			/api/v1/backends/{id} [get]
+// @Param			backendID	path		int										true	"Backend ID"
+// @Success		200			{object}	handler.Response{data=entity.Backend}	"Success"
+// @Failure		400			{object}	error									"Bad Request"
+// @Failure		401			{object}	error									"Unauthorized"
+// @Failure		429			{object}	error									"Too Many Requests"
+// @Failure		404			{object}	error									"Not Found"
+// @Failure		500			{object}	error									"Internal Server Error"
+// @Router			/api/v1/backends/{backendID} [get]
 func (h *Handler) GetBackend() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		// Getting stuff from context

diff --git a/pkg/server/handler/module/handler.go b/pkg/server/handler/module/handler.go
@@ -54,14 +54,14 @@ func (h *Handler) CreateModule() http.HandlerFunc {
 // @Description	Delete the specified module by name
 // @Tags			module
 // @Produce		json
-// @Param			name					path		string							true	"Module Name"
-// @Success		200						{object}	handler.Response{data=string}	"Success"
-// @Failure		400						{object}	error							"Bad Request"
-// @Failure		401						{object}	error							"Unauthorized"
-// @Failure		429						{object}	error							"Too Many Requests"
-// @Failure		404						{object}	error							"Not Found"
-// @Failure		500						{object}	error							"Internal Server Error"
-// @Router			/api/v1/modules/{name} 	[delete]
+// @Param			moduleName						path		string							true	"Module Name"
+// @Success		200								{object}	handler.Response{data=string}	"Success"
+// @Failure		400								{object}	error							"Bad Request"
+// @Failure		401								{object}	error							"Unauthorized"
+// @Failure		429								{object}	error							"Too Many Requests"
+// @Failure		404								{object}	error							"Not Found"
+// @Failure		500								{object}	error							"Internal Server Error"
+// @Router			/api/v1/modules/{moduleName} 	[delete]
 func (h *Handler) DeleteModule() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		// Getting stuff from context.
@@ -83,15 +83,15 @@ func (h *Handler) DeleteModule() http.HandlerFunc {
 // @Tags			module
 // @Accept			json
 // @Produce		json
-// @Param			name					path		string									true	"Module Name"
-// @Param			module					body		request.UpdateModuleRequest				true	"Updated module"
-// @Success		200						{object}	handler.Response{data=entity.Module}	"Success"
-// @Failure		400						{object}	error									"Bad Request"
-// @Failure		401						{object}	error									"Unauthorized"
-// @Failure		429						{object}	error									"Too Many Requests"
-// @Failure		404						{object}	error									"Not Found"
-// @Failure		500						{object}	error									"Internal Server Error"
-// @Router			/api/v1/modules/{name} 																																																																																																																																											[put]
+// @Param			moduleName						path		string									true	"Module Name"
+// @Param			module							body		request.UpdateModuleRequest				true	"Updated module"
+// @Success		200								{object}	handler.Response{data=entity.Module}	"Success"
+// @Failure		400								{object}	error									"Bad Request"
+// @Failure		401								{object}	error									"Unauthorized"
+// @Failure		429								{object}	error									"Too Many Requests"
+// @Failure		404								{object}	error									"Not Found"
+// @Failure		500								{object}	error									"Internal Server Error"
+// @Router			/api/v1/modules/{moduleName} 																																																																																																																																																																												[put]
 func (h *Handler) UpdateModule() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		// Getting stuff from context.
@@ -120,14 +120,14 @@ func (h *Handler) UpdateModule() http.HandlerFunc {
 // @Description	Get module information by module name
 // @Tags			module
 // @Produce		json
-// @Param			name					path		string									true	"Module Name"
-// @Success		200						{object}	handler.Response{data=entity.Module}	"Success"
-// @Failure		400						{object}	error									"Bad Request"
-// @Failure		401						{object}	error									"Unauthorized"
-// @Failure		429						{object}	error									"Too Many Requests"
-// @Failure		404						{object}	error									"Not Found"
-// @Failure		500						{object}	error									"Internal Server Error"
-// @Router			/api/v1/modules/{name} 																																																																																																																									[get]
+// @Param			moduleName						path		string									true	"Module Name"
+// @Success		200								{object}	handler.Response{data=entity.Module}	"Success"
+// @Failure		400								{object}	error									"Bad Request"
+// @Failure		401								{object}	error									"Unauthorized"
+// @Failure		429								{object}	error									"Too Many Requests"
+// @Failure		404								{object}	error									"Not Found"
+// @Failure		500								{object}	error									"Internal Server Error"
+// @Router			/api/v1/modules/{moduleName} 																																																																																																																																																										[get]
 func (h *Handler) GetModule() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		// Getting stuff from context.

diff --git a/pkg/server/handler/organization/handler.go b/pkg/server/handler/organization/handler.go
@@ -60,14 +60,14 @@ func (h *Handler) CreateOrganization() http.HandlerFunc {
 // @Description	Delete specified organization by ID
 // @Tags			organization
 // @Produce		json
-// @Param			id	path		int								true	"Organization ID"
-// @Success		200	{object}	handler.Response{data=string}	"Success"
-// @Failure		400	{object}	error							"Bad Request"
-// @Failure		401	{object}	error							"Unauthorized"
-// @Failure		429	{object}	error							"Too Many Requests"
-// @Failure		404	{object}	error							"Not Found"
-// @Failure		500	{object}	error							"Internal Server Error"
-// @Router			/api/v1/orgs/{id} [delete]
+// @Param			orgID	path		int								true	"Organization ID"
+// @Success		200		{object}	handler.Response{data=string}	"Success"
+// @Failure		400		{object}	error							"Bad Request"
+// @Failure		401		{object}	error							"Unauthorized"
+// @Failure		429		{object}	error							"Too Many Requests"
+// @Failure		404		{object}	error							"Not Found"
+// @Failure		500		{object}	error							"Internal Server Error"
+// @Router			/api/v1/orgs/{orgID} [delete]
 func (h *Handler) DeleteOrganization() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		// Getting stuff from context
@@ -89,15 +89,15 @@ func (h *Handler) DeleteOrganization() http.HandlerFunc {
 // @Tags			organization
 // @Accept			json
 // @Produce		json
-// @Param			id				path		int											true	"Organization ID"
+// @Param			orgID			path		int											true	"Organization ID"
 // @Param			organization	body		request.UpdateOrganizationRequest			true	"Updated organization"
 // @Success		200				{object}	handler.Response{data=entity.Organization}	"Success"
 // @Failure		400				{object}	error										"Bad Request"
 // @Failure		401				{object}	error										"Unauthorized"
 // @Failure		429				{object}	error										"Too Many Requests"
 // @Failure		404				{object}	error										"Not Found"
 // @Failure		500				{object}	error										"Internal Server Error"
-// @Router			/api/v1/orgs/{id} [put]
+// @Router			/api/v1/orgs/{orgID} [put]
 func (h *Handler) UpdateOrganization() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		// Getting stuff from context
@@ -132,14 +132,14 @@ func (h *Handler) UpdateOrganization() http.HandlerFunc {
 // @Description	Get organization information by organization ID
 // @Tags			organization
 // @Produce		json
-// @Param			id	path		int											true	"Organization ID"
-// @Success		200	{object}	handler.Response{data=entity.Organization}	"Success"
-// @Failure		400	{object}	error										"Bad Request"
-// @Failure		401	{object}	error										"Unauthorized"
-// @Failure		429	{object}	error										"Too Many Requests"
-// @Failure		404	{object}	error										"Not Found"
-// @Failure		500	{object}	error										"Internal Server Error"
-// @Router			/api/v1/orgs/{id} [get]
+// @Param			orgID	path		int											true	"Organization ID"
+// @Success		200		{object}	handler.Response{data=entity.Organization}	"Success"
+// @Failure		400		{object}	error										"Bad Request"
+// @Failure		401		{object}	error										"Unauthorized"
+// @Failure		429		{object}	error										"Too Many Requests"
+// @Failure		404		{object}	error										"Not Found"
+// @Failure		500		{object}	error										"Internal Server Error"
+// @Router			/api/v1/orgs/{orgID} [get]
 func (h *Handler) GetOrganization() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		// Getting stuff from context

diff --git a/pkg/server/handler/project/handler.go b/pkg/server/handler/project/handler.go
@@ -70,14 +70,14 @@ func (h *Handler) CreateProject() http.HandlerFunc {
 // @Description	Delete specified project by ID
 // @Tags			project
 // @Produce		json
-// @Param			project_id	path		int								true	"Project ID"
+// @Param			projectID	path		int								true	"Project ID"
 // @Success		200			{object}	handler.Response{data=string}	"Success"
 // @Failure		400			{object}	error							"Bad Request"
 // @Failure		401			{object}	error							"Unauthorized"
 // @Failure		429			{object}	error							"Too Many Requests"
 // @Failure		404			{object}	error							"Not Found"
 // @Failure		500			{object}	error							"Internal Server Error"
-// @Router			/api/v1/projects/{project_id} [delete]
+// @Router			/api/v1/projects/{projectID} [delete]
 func (h *Handler) DeleteProject() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		// Getting stuff from context
@@ -99,15 +99,15 @@ func (h *Handler) DeleteProject() http.HandlerFunc {
 // @Tags			project
 // @Accept			json
 // @Produce		json
-// @Param			project_id	path		uint									true	"Project ID"
+// @Param			projectID	path		uint									true	"Project ID"
 // @Param			project		body		request.UpdateProjectRequest			true	"Updated project"
 // @Success		200			{object}	handler.Response{data=entity.Project}	"Success"
 // @Failure		400			{object}	error									"Bad Request"
 // @Failure		401			{object}	error									"Unauthorized"
 // @Failure		429			{object}	error									"Too Many Requests"
 // @Failure		404			{object}	error									"Not Found"
 // @Failure		500			{object}	error									"Internal Server Error"
-// @Router			/api/v1/projects/{project_id} [put]
+// @Router			/api/v1/projects/{projectID} [put]
 func (h *Handler) UpdateProject() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		// Getting stuff from context
@@ -141,14 +141,14 @@ func (h *Handler) UpdateProject() http.HandlerFunc {
 // @Description	Get project information by project ID
 // @Tags			project
 // @Produce		json
-// @Param			project_id	path		uint									true	"Project ID"
+// @Param			projectID	path		uint									true	"Project ID"
 // @Success		200			{object}	handler.Response{data=entity.Project}	"Success"
 // @Failure		400			{object}	error									"Bad Request"
 // @Failure		401			{object}	error									"Unauthorized"
 // @Failure		429			{object}	error									"Too Many Requests"
 // @Failure		404			{object}	error									"Not Found"
 // @Failure		500			{object}	error									"Internal Server Error"
-// @Router			/api/v1/projects/{project_id} [get]
+// @Router			/api/v1/projects/{projectID} [get]
 func (h *Handler) GetProject() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		// Getting stuff from context

diff --git a/pkg/server/handler/resource/handler.go b/pkg/server/handler/resource/handler.go
@@ -20,14 +20,19 @@ import (
 // @Description	List resource information
 // @Tags			resource
 // @Produce		json
-// @Param			page		query		uint														false	"The current page to fetch. Default to 1"
-// @Param			pageSize	query		uint														false	"The size of the page. Default to 10"
-// @Success		200			{object}	handler.Response{data=[]response.PaginatedResourceResponse}	"Success"
-// @Failure		400			{object}	error														"Bad Request"
-// @Failure		401			{object}	error														"Unauthorized"
-// @Failure		429			{object}	error														"Too Many Requests"
-// @Failure		404			{object}	error														"Not Found"
-// @Failure		500			{object}	error														"Internal Server Error"
+// @Param			orgID			query		uint														false	"The organization ID"
+// @Param			projectID		query		uint														false	"The project ID"
+// @Param			stackID			query		uint														false	"The stack ID"
+// @Param			resourceType	query		string														false	"The resource type"
+// @Param			resourcePlane	query		string														false	"The resource plane"
+// @Param			page			query		uint														false	"The current page to fetch. Default to 1"
+// @Param			pageSize		query		uint														false	"The size of the page. Default to 10"
+// @Success		200				{object}	handler.Response{data=[]response.PaginatedResourceResponse}	"Success"
+// @Failure		400				{object}	error														"Bad Request"
+// @Failure		401				{object}	error														"Unauthorized"
+// @Failure		429				{object}	error														"Too Many Requests"
+// @Failure		404				{object}	error														"Not Found"
+// @Failure		500				{object}	error														"Internal Server Error"
 // @Router			/api/v1/resources [get]
 func (h *Handler) ListResources() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
@@ -65,14 +70,14 @@ func (h *Handler) ListResources() http.HandlerFunc {
 // @Description	Get resource information by resource ID
 // @Tags			resource
 // @Produce		json
-// @Param			id	path		int										true	"Resource ID"
-// @Success		200	{object}	handler.Response{data=entity.Resource}	"Success"
-// @Failure		400	{object}	error									"Bad Request"
-// @Failure		401	{object}	error									"Unauthorized"
-// @Failure		429	{object}	error									"Too Many Requests"
-// @Failure		404	{object}	error									"Not Found"
-// @Failure		500	{object}	error									"Internal Server Error"
-// @Router			/api/v1/resources/{id} [get]
+// @Param			resourceID	path		int										true	"Resource ID"
+// @Success		200			{object}	handler.Response{data=entity.Resource}	"Success"
+// @Failure		400			{object}	error									"Bad Request"
+// @Failure		401			{object}	error									"Unauthorized"
+// @Failure		429			{object}	error									"Too Many Requests"
+// @Failure		404			{object}	error									"Not Found"
+// @Failure		500			{object}	error									"Internal Server Error"
+// @Router			/api/v1/resources/{resourceID} [get]
 func (h *Handler) GetResource() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		// Getting stuff from context
@@ -94,12 +99,12 @@ func (h *Handler) GetResource() http.HandlerFunc {
 // @Tags			resource
 // @Produce		json
 // @Param			stackID	query		uint										true	"Stack ID"
-// @Success		200			{object}	handler.Response{data=entity.ResourceGraph}	"Success"
-// @Failure		400			{object}	error										"Bad Request"
-// @Failure		401			{object}	error										"Unauthorized"
-// @Failure		429			{object}	error										"Too Many Requests"
-// @Failure		404			{object}	error										"Not Found"
-// @Failure		500			{object}	error										"Internal Server Error"
+// @Success		200		{object}	handler.Response{data=entity.ResourceGraph}	"Success"
+// @Failure		400		{object}	error										"Bad Request"
+// @Failure		401		{object}	error										"Unauthorized"
+// @Failure		429		{object}	error										"Too Many Requests"
+// @Failure		404		{object}	error										"Not Found"
+// @Failure		500		{object}	error										"Internal Server Error"
 // @Router			/api/v1/resources/graph [get]
 func (h *Handler) GetResourceGraph() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {