Chore: Move swagger definitions to the handlers (#52643)

pkg/api/folder.go

@@ -18,6 +18,17 @@ import (
 	"github.com/grafana/grafana/pkg/web"
 )
 
+// swagger:route GET /folders folders getFolders
+//
+// Get all folders.
+//
+// Returns all folders that the authenticated user has permission to view.
+//
+// Responses:
+// 200: getFoldersResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 500: internalServerError
 func (hs *HTTPServer) GetFolders(c *models.ReqContext) response.Response {
 	folders, err := hs.folderService.GetFolders(c.Req.Context(), c.SignedInUser, c.OrgId, c.QueryInt64("limit"), c.QueryInt64("page"))
 
@@ -46,6 +57,16 @@ func (hs *HTTPServer) GetFolders(c *models.ReqContext) response.Response {
 	return response.JSON(http.StatusOK, result)
 }
 
+// swagger:route GET /folders/{folder_uid} folders getFolderByUID
+//
+// Get folder by uid.
+//
+// Responses:
+// 200: folderResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (hs *HTTPServer) GetFolderByUID(c *models.ReqContext) response.Response {
 	folder, err := hs.folderService.GetFolderByUID(c.Req.Context(), c.SignedInUser, c.OrgId, web.Params(c.Req)[":uid"])
 	if err != nil {
@@ -56,6 +77,18 @@ func (hs *HTTPServer) GetFolderByUID(c *models.ReqContext) response.Response {
 	return response.JSON(http.StatusOK, hs.toFolderDto(c, g, folder))
 }
 
+// swagger:route GET /folders/id/{folder_id} folders getFolderByID
+//
+// Get folder by id.
+//
+// Returns the folder identified by id.
+//
+// Responses:
+// 200: folderResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (hs *HTTPServer) GetFolderByID(c *models.ReqContext) response.Response {
 	id, err := strconv.ParseInt(web.Params(c.Req)[":id"], 10, 64)
 	if err != nil {
@@ -70,6 +103,17 @@ func (hs *HTTPServer) GetFolderByID(c *models.ReqContext) response.Response {
 	return response.JSON(http.StatusOK, hs.toFolderDto(c, g, folder))
 }
 
+// swagger:route POST /folders folders createFolder
+//
+// Create folder.
+//
+// Responses:
+// 200: folderResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 403: forbiddenError
+// 409: conflictError
+// 500: internalServerError
 func (hs *HTTPServer) CreateFolder(c *models.ReqContext) response.Response {
 	cmd := models.CreateFolderCommand{}
 	if err := web.Bind(c.Req, &cmd); err != nil {
@@ -92,6 +136,18 @@ func (hs *HTTPServer) CreateFolder(c *models.ReqContext) response.Response {
 	return response.JSON(http.StatusOK, hs.toFolderDto(c, g, folder))
 }
 
+// swagger:route PUT /folders/{folder_uid} folders updateFolder
+//
+// Update folder.
+//
+// Responses:
+// 200: folderResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 409: conflictError
+// 500: internalServerError
 func (hs *HTTPServer) UpdateFolder(c *models.ReqContext) response.Response {
 	cmd := models.UpdateFolderCommand{}
 	if err := web.Bind(c.Req, &cmd); err != nil {
@@ -114,6 +170,19 @@ func (hs *HTTPServer) UpdateFolder(c *models.ReqContext) response.Response {
 	return response.JSON(http.StatusOK, hs.toFolderDto(c, g, cmd.Result))
 }
 
+// swagger:route DELETE /folders/{folder_uid} folders deleteFolder
+//
+// Delete folder.
+//
+// Deletes an existing folder identified by UID along with all dashboards (and their alerts) stored in the folder. This operation cannot be reverted.
+//
+// Responses:
+// 200: deleteFolderResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (hs *HTTPServer) DeleteFolder(c *models.ReqContext) response.Response { // temporarily adding this function to HTTPServer, will be removed from HTTPServer when librarypanels featuretoggle is removed
 	err := hs.LibraryElementService.DeleteLibraryElementsInFolder(c.Req.Context(), c.SignedInUser, web.Params(c.Req)[":uid"])
 	if err != nil {
@@ -177,3 +246,101 @@ func (hs *HTTPServer) toFolderDto(c *models.ReqContext, g guardian.DashboardGuar
 		AccessControl: hs.getAccessControlMetadata(c, c.OrgId, dashboards.ScopeFoldersPrefix, folder.Uid),
 	}
 }
+
+// swagger:parameters getFolders
+type GetFoldersParams struct {
+	// Limit the maximum number of folders to return
+	// in:query
+	// required:false
+	// default:1000
+	Limit int64 `json:"limit"`
+	// Page index for starting fetching folders
+	// in:query
+	// required:false
+	// default:1
+	Page int64 `json:"page"`
+}
+
+// swagger:parameters getFolderByUID
+type GetFolderByUIDParams struct {
+	// in:path
+	// required:true
+	FolderUID string `json:"folder_uid"`
+}
+
+// swagger:parameters updateFolder
+type UpdateFolderParams struct {
+	// in:path
+	// required:true
+	FolderUID string `json:"folder_uid"`
+	// To change the unique identifier (uid), provide another one.
+	// To overwrite an existing folder with newer version, set `overwrite` to `true`.
+	// Provide the current version to safelly update the folder: if the provided version differs from the stored one the request will fail, unless `overwrite` is `true`.
+	//
+	// in:body
+	// required:true
+	Body models.UpdateFolderCommand `json:"body"`
+}
+
+// swagger:parameters getFolderByID
+type GetFolderByIDParams struct {
+	// in:path
+	// required:true
+	FolderID int64 `json:"folder_id"`
+}
+
+// swagger:parameters createFolder
+type CreateFolderParams struct {
+	// in:body
+	// required:true
+	Body models.CreateFolderCommand `json:"body"`
+}
+
+// swagger:parameters deleteFolder
+type DeleteFolderParams struct {
+	// in:path
+	// required:true
+	FolderUID string `json:"folder_uid"`
+	// If `true` any Grafana 8 Alerts under this folder will be deleted.
+	// Set to `false` so that the request will fail if the folder contains any Grafana 8 Alerts.
+	// in:query
+	// required:false
+	// default:false
+	ForceDeleteRules bool `json:"forceDeleteRules"`
+}
+
+// swagger:response getFoldersResponse
+type GetFoldersResponse struct {
+	// The response message
+	// in: body
+	Body []dtos.FolderSearchHit `json:"body"`
+}
+
+// swagger:response folderResponse
+type FolderResponse struct {
+	// The response message
+	// in: body
+	Body dtos.Folder `json:"body"`
+}
+
+// swagger:response deleteFolderResponse
+type DeleteFolderResponse struct {
+	// The response message
+	// in: body
+	Body struct {
+		// ID Identifier of the deleted folder.
+		// required: true
+		// example: 65
+		ID int64 `json:"id"`
+
+		// Title of the deleted folder.
+		// required: true
+		// example: My Folder
+		Title string `json:"title"`
+
+		// Message Message of the deleted folder.
+		// required: true
+		// example: Folder My Folder deleted
+		Message string `json:"message"`
+	} `json:"body"`
+}