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

pkg/services/libraryelements/api.go

@@ -24,7 +24,19 @@ func (l *LibraryElementService) registerAPIEndpoints() {
 	})
 }
 
-// createHandler handles POST /api/library-elements.
+// swagger:route POST /library-elements library_elements createLibraryElement
+//
+// Create library element.
+//
+// Creates a new library element.
+//
+// Responses:
+// 200: getLibraryElementResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (l *LibraryElementService) createHandler(c *models.ReqContext) response.Response {
 	cmd := CreateLibraryElementCommand{}
 	if err := web.Bind(c.Req, &cmd); err != nil {
@@ -61,7 +73,20 @@ func (l *LibraryElementService) createHandler(c *models.ReqContext) response.Res
 	return response.JSON(http.StatusOK, LibraryElementResponse{Result: element})
 }
 
-// deleteHandler handles DELETE /api/library-elements/:uid.
+// swagger:route DELETE /library-elements/{library_element_uid} library_elements deleteLibraryElementByUID
+//
+// Delete library element.
+//
+// Deletes an existing library element as specified by the UID. This operation cannot be reverted.
+// You cannot delete a library element that is connected. This operation cannot be reverted.
+//
+// Responses:
+// 200: okResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (l *LibraryElementService) deleteHandler(c *models.ReqContext) response.Response {
 	id, err := l.deleteLibraryElement(c.Req.Context(), c.SignedInUser, web.Params(c.Req)[":uid"])
 	if err != nil {
@@ -74,7 +99,17 @@ func (l *LibraryElementService) deleteHandler(c *models.ReqContext) response.Res
 	})
 }
 
-// getHandler handles GET  /api/library-elements/:uid.
+// swagger:route GET /library-elements/{library_element_uid} library_elements getLibraryElementByUID
+//
+// Get library element by UID.
+//
+// Returns a library element with the given UID.
+//
+// Responses:
+// 200: getLibraryElementResponse
+// 401: unauthorisedError
+// 404: notFoundError
+// 500: internalServerError
 func (l *LibraryElementService) getHandler(c *models.ReqContext) response.Response {
 	element, err := l.getLibraryElementByUid(c.Req.Context(), c.SignedInUser, web.Params(c.Req)[":uid"])
 	if err != nil {
@@ -84,7 +119,18 @@ func (l *LibraryElementService) getHandler(c *models.ReqContext) response.Respon
 	return response.JSON(http.StatusOK, LibraryElementResponse{Result: element})
 }
 
-// getAllHandler handles GET /api/library-elements/.
+// swagger:route GET /library-elements library_elements getLibraryElements
+//
+// Get all library elements.
+//
+// Returns a list of all library elements the authenticated user has permission to view.
+// Use the `perPage` query parameter to control the maximum number of library elements returned; the default limit is `100`.
+// You can also use the `page` query parameter to fetch library elements from any page other than the first one.
+//
+// Responses:
+// 200: getLibraryElementsResponse
+// 401: unauthorisedError
+// 500: internalServerError
 func (l *LibraryElementService) getAllHandler(c *models.ReqContext) response.Response {
 	query := searchLibraryElementsQuery{
 		perPage:       c.QueryInt("perPage"),
@@ -104,7 +150,20 @@ func (l *LibraryElementService) getAllHandler(c *models.ReqContext) response.Res
 	return response.JSON(http.StatusOK, LibraryElementSearchResponse{Result: elementsResult})
 }
 
-// patchHandler handles PATCH /api/library-elements/:uid
+// swagger:route PATCH /library-elements/{library_element_uid} library_elements updateLibraryElement
+//
+// Update library element.
+//
+// Updates an existing library element identified by uid.
+//
+// Responses:
+// 200: getLibraryElementResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 412: preconditionFailedError
+// 500: internalServerError
 func (l *LibraryElementService) patchHandler(c *models.ReqContext) response.Response {
 	cmd := PatchLibraryElementCommand{}
 	if err := web.Bind(c.Req, &cmd); err != nil {
@@ -141,7 +200,17 @@ func (l *LibraryElementService) patchHandler(c *models.ReqContext) response.Resp
 	return response.JSON(http.StatusOK, LibraryElementResponse{Result: element})
 }
 
-// getConnectionsHandler handles GET /api/library-panels/:uid/connections/.
+// swagger:route GET /library-elements/{library_element_uid}/connections/ library_elements getLibraryElementConnections
+//
+// Get library element connections.
+//
+// Returns a list of connections for a library element based on the UID specified.
+//
+// Responses:
+// 200: getLibraryElementConnectionsResponse
+// 401: unauthorisedError
+// 404: notFoundError
+// 500: internalServerError
 func (l *LibraryElementService) getConnectionsHandler(c *models.ReqContext) response.Response {
 	connections, err := l.getConnections(c.Req.Context(), c.SignedInUser, web.Params(c.Req)[":uid"])
 	if err != nil {
@@ -151,7 +220,17 @@ func (l *LibraryElementService) getConnectionsHandler(c *models.ReqContext) resp
 	return response.JSON(http.StatusOK, LibraryElementConnectionsResponse{Result: connections})
 }
 
-// getByNameHandler handles GET /api/library-elements/name/:name/.
+// swagger:route GET /library-elements/name/{library_element_name} library_elements getLibraryElementByName
+//
+// Get library element by name.
+//
+// Returns a library element with the given name.
+//
+// Responses:
+// 200: getLibraryElementResponse
+// 401: unauthorisedError
+// 404: notFoundError
+// 500: internalServerError
 func (l *LibraryElementService) getByNameHandler(c *models.ReqContext) response.Response {
 	elements, err := l.getLibraryElementsByName(c.Req.Context(), c.SignedInUser, web.Params(c.Req)[":name"])
 	if err != nil {
@@ -191,3 +270,119 @@ func toLibraryElementError(err error, message string) response.Response {
 	}
 	return response.Error(500, message, err)
 }
+
+// swagger:parameters getLibraryElementByUID getLibraryElementConnections
+type LibraryElementByUID struct {
+	// in:path
+	// required:true
+	UID string `json:"library_element_uid"`
+}
+
+// swagger:parameters getLibraryElementByUID
+type GetLibraryElementByUIDParams struct {
+	// in:path
+	// required:true
+	UID string `json:"library_element_uid"`
+}
+
+// swagger:parameters GetLibraryElementConnectionsParams
+type GetLibraryElementConnectionsParams struct {
+	// in:path
+	// required:true
+	UID string `json:"library_element_uid"`
+}
+
+// swagger:parameters deleteLibraryElementByUID
+type DeleteLibraryElementByUIDParams struct {
+	// in:path
+	// required:true
+	UID string `json:"library_element_uid"`
+}
+
+// swagger:parameters getLibraryElementByName
+type LibraryElementByNameParams struct {
+	// in:path
+	// required:true
+	Name string `json:"library_element_name"`
+}
+
+// swagger:parameters getLibraryElements
+type GetLibraryElementsParams struct {
+	// Part of the name or description searched for.
+	// in:query
+	// required:false
+	SearchString string `json:"searchString"`
+	// Kind of element to search for.
+	// in:query
+	// required:false
+	// Description:
+	// * 1 - library panels
+	// * 2 - library variables
+	// enum: 1,2
+	Kind int `json:"kind"`
+	// Sort order of elements.
+	// in:query
+	// required:false
+	// Description:
+	// * alpha-asc: ascending
+	// * alpha-desc: descending
+	// Enum: alpha-asc,alpha-desc
+	SortDirection string `json:"sortDirection"`
+	// A comma separated list of types to filter the elements by
+	// in:query
+	// required:false
+	TypeFilter string `json:"typeFilter"`
+	// Element UID to exclude from search results.
+	// in:query
+	// required:false
+	ExcludeUID string `json:"excludeUid"`
+	// A comma separated list of folder ID(s) to filter the elements by.
+	// in:query
+	// required:false
+	FolderFilter string `json:"folderFilter"`
+	// The number of results per page.
+	// in:query
+	// required:false
+	// default: 100
+	PerPage int `json:"perPage"`
+	// The page for a set of records, given that only perPage records are returned at a time. Numbering starts at 1.
+	// in:query
+	// required:false
+	// default: 1
+	Page int `json:"page"`
+}
+
+// swagger:parameters createLibraryElement
+type CreateLibraryElementParams struct {
+	// in:body
+	// required:true
+	Body CreateLibraryElementCommand `json:"body"`
+}
+
+// swagger:parameters updateLibraryElement
+type UpdateLibraryElementParam struct {
+	// in:body
+	// required:true
+	Body PatchLibraryElementCommand `json:"body"`
+	// in:path
+	// required:true
+	UID string `json:"library_element_uid"`
+}
+
+// swagger:response getLibraryElementsResponse
+type GetLibraryElementsResponse struct {
+	// in: body
+	Body LibraryElementSearchResponse `json:"body"`
+}
+
+// swagger:response getLibraryElementResponse
+type GetLibraryElementResponse struct {
+	// in: body
+	Body LibraryElementResponse `json:"body"`
+}
+
+// swagger:response getLibraryElementConnectionsResponse
+type GetLibraryElementConnectionsResponse struct {
+	// in: body
+	Body LibraryElementConnectionsResponse `json:"body"`
+}