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

2025-02-25 18:55:37 -06:00 · 2022-07-27 16:54:37 +03:00
parent c968b76279
commit 7ba076de10
76 changed files with 6022 additions and 6161 deletions
--- a/pkg/services/correlations/api.go
+++ b/pkg/services/correlations/api.go
@@ -24,7 +24,17 @@ func (s *CorrelationsService) registerAPIEndpoints() {
 	})
 }

-// createHandler handles POST /datasources/uid/:uid/correlations
+// swagger:route POST /datasources/uid/{sourceUID}/correlations correlations createCorrelation
+//
+// Add correlation.
+//
+// Responses:
+// 200: createCorrelationResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (s *CorrelationsService) createHandler(c *models.ReqContext) response.Response {
 	cmd := CreateCorrelationCommand{}
 	if err := web.Bind(c.Req, &cmd); err != nil {
@@ -46,10 +56,35 @@ func (s *CorrelationsService) createHandler(c *models.ReqContext) response.Respo
 		return response.Error(http.StatusInternalServerError, "Failed to add correlation", err)
 	}

-	return response.JSON(http.StatusOK, CreateCorrelationResponse{Result: correlation, Message: "Correlation created"})
+	return response.JSON(http.StatusOK, CreateCorrelationResponseBody{Result: correlation, Message: "Correlation created"})
 }

-// deleteHandler handles DELETE /datasources/uid/:uid/correlations/:correlationUID
+// swagger:parameters createCorrelation
+type CreateCorrelationParams struct {
+	// in:body
+	// required:true
+	Body CreateCorrelationCommand `json:"body"`
+	// in:path
+	// required:true
+	SourceUID string `json:"sourceUID"`
+}
+
+//swagger:response createCorrelationResponse
+type CreateCorrelationResponse struct {
+	// in: body
+	Body CreateCorrelationResponseBody `json:"body"`
+}
+
+// swagger:route DELETE /datasources/uid/{uid}/correlations/{correlationUID} correlations deleteCorrelation
+//
+// Delete a correlation.
+//
+// Responses:
+// 200: deleteCorrelationResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (s *CorrelationsService) deleteHandler(c *models.ReqContext) response.Response {
 	cmd := DeleteCorrelationCommand{
 		UID:       web.Params(c.Req)[":correlationUID"],
@@ -74,5 +109,21 @@ func (s *CorrelationsService) deleteHandler(c *models.ReqContext) response.Respo
 		return response.Error(http.StatusInternalServerError, "Failed to delete correlation", err)
 	}

-	return response.JSON(http.StatusOK, DeleteCorrelationResponse{Message: "Correlation deleted"})
+	return response.JSON(http.StatusOK, DeleteCorrelationResponseBody{Message: "Correlation deleted"})
+}
+
+// swagger:parameters deleteCorrelation
+type DeleteCorrelationParams struct {
+	// in:path
+	// required:true
+	DatasourceUID string `json:"uid"`
+	// in:path
+	// required:true
+	CorrelationUID string `json:"correlationUID"`
+}
+
+//swagger:response deleteCorrelationResponse
+type DeleteCorrelationResponse struct {
+	// in: body
+	Body DeleteCorrelationResponseBody `json:"body"`
 }
--- a/pkg/services/correlations/models.go
+++ b/pkg/services/correlations/models.go
@@ -34,7 +34,7 @@ type Correlation struct {

 // CreateCorrelationResponse is the response struct for CreateCorrelationCommand
 // swagger:model
-type CreateCorrelationResponse struct {
+type CreateCorrelationResponseBody struct {
 	Result Correlation `json:"result"`
 	// example: Correlation created
 	Message string `json:"message"`
@@ -59,7 +59,7 @@ type CreateCorrelationCommand struct {
 }

 // swagger:model
-type DeleteCorrelationResponse struct {
+type DeleteCorrelationResponseBody struct {
 	// example: Correlation deleted
 	Message string `json:"message"`
 }
--- a/pkg/services/dashboardimport/api/api.go
+++ b/pkg/services/dashboardimport/api/api.go
@@ -43,6 +43,17 @@ func (api *ImportDashboardAPI) RegisterAPIEndpoints(routeRegister routing.RouteR
 	}, middleware.ReqSignedIn)
 }

+// swagger:route POST /dashboards/import dashboards importDashboard
+//
+// Import dashboard.
+//
+// Responses:
+// 200: importDashboardResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 412: preconditionFailedError
+// 422: unprocessableEntityError
+// 500: internalServerError
 func (api *ImportDashboardAPI) ImportDashboard(c *models.ReqContext) response.Response {
 	req := dashboardimport.ImportDashboardRequest{}
 	if err := web.Bind(c.Req, &req); err != nil {
@@ -80,3 +91,16 @@ type quotaServiceFunc func(c *models.ReqContext, target string) (bool, error)
 func (fn quotaServiceFunc) QuotaReached(c *models.ReqContext, target string) (bool, error) {
 	return fn(c, target)
 }
+
+// swagger:parameters importDashboard
+type ImportDashboardParams struct {
+	// in:body
+	// required:true
+	Body dashboardimport.ImportDashboardRequest
+}
+
+// swagger:response importDashboardResponse
+type ImportDashboardResponse struct {
+	// in: body
+	Body dashboardimport.ImportDashboardResponse `json:"body"`
+}
--- a/pkg/services/libraryelements/api.go
+++ b/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"`
+}
--- a/pkg/services/queryhistory/api.go
+++ b/pkg/services/queryhistory/api.go
@@ -25,7 +25,17 @@ func (s *QueryHistoryService) registerAPIEndpoints() {
 	})
 }

-// createHandler handles POST /api/query-history
+// swagger:route POST /query-history query_history createQuery
+//
+// Add query to query history.
+//
+// Adds new query to query history.
+//
+// Responses:
+// 200: getQueryHistoryResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 500: internalServerError
 func (s *QueryHistoryService) createHandler(c *models.ReqContext) response.Response {
 	cmd := CreateQueryInQueryHistoryCommand{}
 	if err := web.Bind(c.Req, &cmd); err != nil {
@@ -40,7 +50,18 @@ func (s *QueryHistoryService) createHandler(c *models.ReqContext) response.Respo
 	return response.JSON(http.StatusOK, QueryHistoryResponse{Result: query})
 }

-// searchHandler handles GET /api/query-history
+// swagger:route GET /query-history query_history searchQueries
+//
+// Query history search.
+//
+// Returns a list of queries in the query history that matches the search criteria.
+// Query history search supports pagination. Use the `limit` parameter to control the maximum number of queries returned; the default limit is 100.
+// You can also use the `page` query parameter to fetch queries from any page other than the first one.
+//
+// Responses:
+// 200: getQueryHistorySearchResponse
+// 401: unauthorisedError
+// 500: internalServerError
 func (s *QueryHistoryService) searchHandler(c *models.ReqContext) response.Response {
 	timeRange := legacydata.NewDataTimeRange(c.Query("from"), c.Query("to"))

@@ -63,7 +84,16 @@ func (s *QueryHistoryService) searchHandler(c *models.ReqContext) response.Respo
 	return response.JSON(http.StatusOK, QueryHistorySearchResponse{Result: result})
 }

-// deleteHandler handles DELETE /api/query-history/:uid
+// swagger:route DELETE /query-history/{query_history_uid} query_history deleteQuery
+//
+// Delete query in query history.
+//
+// Deletes an existing query in query history as specified by the UID. This operation cannot be reverted.
+//
+// Responses:
+// 200: getQueryHistoryDeleteQueryResponse
+// 401: unauthorisedError
+// 500: internalServerError
 func (s *QueryHistoryService) deleteHandler(c *models.ReqContext) response.Response {
 	queryUID := web.Params(c.Req)[":uid"]
 	if len(queryUID) > 0 && !util.IsValidShortUID(queryUID) {
@@ -81,7 +111,17 @@ func (s *QueryHistoryService) deleteHandler(c *models.ReqContext) response.Respo
 	})
 }

-// patchCommentHandler handles PATCH /api/query-history/:uid
+// swagger:route PATCH /query-history/{query_history_uid} query_history patchQueryComment
+//
+// Update comment for query in query history.
+//
+// Updates comment for query in query history as specified by the UID.
+//
+// Responses:
+// 200: getQueryHistoryResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 500: internalServerError
 func (s *QueryHistoryService) patchCommentHandler(c *models.ReqContext) response.Response {
 	queryUID := web.Params(c.Req)[":uid"]
 	if len(queryUID) > 0 && !util.IsValidShortUID(queryUID) {
@@ -101,7 +141,16 @@ func (s *QueryHistoryService) patchCommentHandler(c *models.ReqContext) response
 	return response.JSON(http.StatusOK, QueryHistoryResponse{Result: query})
 }

-// starHandler handles POST /api/query-history/star/:uid
+// swagger:route POST /query-history/star/{query_history_uid} query_history starQuery
+//
+// Add star to query in query history.
+//
+// Adds star to query in query history as specified by the UID.
+//
+// Responses:
+// 200: getQueryHistoryResponse
+// 401: unauthorisedError
+// 500: internalServerError
 func (s *QueryHistoryService) starHandler(c *models.ReqContext) response.Response {
 	queryUID := web.Params(c.Req)[":uid"]
 	if len(queryUID) > 0 && !util.IsValidShortUID(queryUID) {
@@ -116,7 +165,16 @@ func (s *QueryHistoryService) starHandler(c *models.ReqContext) response.Respons
 	return response.JSON(http.StatusOK, QueryHistoryResponse{Result: query})
 }

-// starHandler handles DELETE /api/query-history/star/:uid
+// swagger:route DELETE /query-history/star/{query_history_uid} query_history unstarQuery
+//
+// Remove star to query in query history.
+//
+// Removes star from query in query history as specified by the UID.
+//
+// Responses:
+// 200: getQueryHistoryResponse
+// 401: unauthorisedError
+// 500: internalServerError
 func (s *QueryHistoryService) unstarHandler(c *models.ReqContext) response.Response {
 	queryUID := web.Params(c.Req)[":uid"]
 	if len(queryUID) > 0 && !util.IsValidShortUID(queryUID) {
@@ -131,7 +189,17 @@ func (s *QueryHistoryService) unstarHandler(c *models.ReqContext) response.Respo
 	return response.JSON(http.StatusOK, QueryHistoryResponse{Result: query})
 }

-// starHandler handles POST /api/query-history/migrate
+// swagger:route POST /query-history/migrate query_history migrateQueries
+//
+// Migrate queries to query history.
+//
+// Adds multiple queries to query history.
+//
+// Responses:
+// 200: getQueryHistoryMigrationResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 500: internalServerError
 func (s *QueryHistoryService) migrateHandler(c *models.ReqContext) response.Response {
 	cmd := MigrateQueriesToQueryHistoryCommand{}
 	if err := web.Bind(c.Req, &cmd); err != nil {
@@ -145,3 +213,95 @@ func (s *QueryHistoryService) migrateHandler(c *models.ReqContext) response.Resp

 	return response.JSON(http.StatusOK, QueryHistoryMigrationResponse{Message: "Query history successfully migrated", TotalCount: totalCount, StarredCount: starredCount})
 }
+
+// swagger:parameters starQuery patchQueryComment deleteQuery unstarQuery
+type QueryHistoryByUID struct {
+	// in:path
+	// required:true
+	UID string `json:"query_history_uid"`
+}
+
+// swagger:parameters searchQueries
+type SearchQueriesParams struct {
+	// List of data source UIDs to search for
+	// in:query
+	// required: false
+	// type: array
+	// collectionFormat: multi
+	DatasourceUid []string `json:"datasourceUid"`
+	// Text inside query or comments that is searched for
+	// in:query
+	// required: false
+	SearchString string `json:"searchString"`
+	// Flag indicating if only starred queries should be returned
+	// in:query
+	// required: false
+	OnlyStarred bool `json:"onlyStarred"`
+	// Sort method
+	// in:query
+	// required: false
+	// default: time-desc
+	// Enum: time-desc,time-asc
+	Sort string `json:"sort"`
+	// Use this parameter to access hits beyond limit. Numbering starts at 1. limit param acts as page size.
+	// in:query
+	// required: false
+	Page int `json:"page"`
+	// Limit the number of returned results
+	// in:query
+	// required: false
+	Limit int `json:"limit"`
+	// From range for the query history search
+	// in:query
+	// required: false
+	From int64 `json:"from"`
+	// To range for the query history search
+	// in:query
+	// required: false
+	To int64 `json:"to"`
+}
+
+// swagger:parameters createQuery
+type CreateQueryParams struct {
+	// in:body
+	// required:true
+	Body CreateQueryInQueryHistoryCommand `json:"body"`
+}
+
+// swagger:parameters patchQueryComment
+type PatchQueryCommentParams struct {
+	// in:body
+	// required:true
+	Body PatchQueryCommentInQueryHistoryCommand `json:"body"`
+}
+
+// swagger:parameters migrateQueries
+type MigrateQueriesParams struct {
+	// in:body
+	// required:true
+	Body MigrateQueriesToQueryHistoryCommand `json:"body"`
+}
+
+//swagger:response getQueryHistorySearchResponse
+type GetQueryHistorySearchResponse struct {
+	// in: body
+	Body QueryHistorySearchResponse `json:"body"`
+}
+
+// swagger:response getQueryHistoryResponse
+type GetQueryHistoryResponse struct {
+	// in: body
+	Body QueryHistoryResponse `json:"body"`
+}
+
+// swagger:response getQueryHistoryDeleteQueryResponse
+type GetQueryHistoryDeleteQueryResponse struct {
+	// in: body
+	Body QueryHistoryDeleteQueryResponse `json:"body"`
+}
+
+// swagger:response getQueryHistoryMigrationResponse
+type GetQueryHistoryMigrationResponse struct {
+	// in: body
+	Body QueryHistoryMigrationResponse `json:"body"`
+}
--- a/pkg/services/searchusers/searchusers.go
+++ b/pkg/services/searchusers/searchusers.go
@@ -23,6 +23,17 @@ func ProvideUsersService(sqlStore sqlstore.Store, searchUserFilter models.Search
 	return &OSSService{sqlStore: sqlStore, searchUserFilter: searchUserFilter}
 }

+// swagger:route GET /users users searchUsers
+//
+// Get users.
+//
+// Returns all users that the authenticated user has permission to view, admin permission required.
+//
+// Responses:
+// 200: searchUsersResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 500: internalServerError
 func (s *OSSService) SearchUsers(c *models.ReqContext) response.Response {
 	query, err := s.SearchUser(c)
 	if err != nil {
@@ -32,6 +43,16 @@ func (s *OSSService) SearchUsers(c *models.ReqContext) response.Response {
 	return response.JSON(http.StatusOK, query.Result.Users)
 }

+// swagger:route GET /users/search users searchUsersWithPaging
+//
+// Get users with paging.
+//
+// Responses:
+// 200: searchUsersResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (s *OSSService) SearchUsersWithPaging(c *models.ReqContext) response.Response {
 	query, err := s.SearchUser(c)
 	if err != nil {
--- a/pkg/services/serviceaccounts/api/api.go
+++ b/pkg/services/serviceaccounts/api/api.go
@@ -80,7 +80,21 @@ func (api *ServiceAccountsAPI) RegisterAPIEndpoints() {
 	})
 }

-// POST /api/serviceaccounts
+// swagger:route POST /serviceaccounts service_accounts createServiceAccount
+//
+// Create service account
+//
+// Required permissions (See note in the [introduction](https://grafana.com/docs/grafana/latest/developers/http_api/serviceaccount/#service-account-api) for an explanation):
+// action: `serviceaccounts:write` scope: `serviceaccounts:*`
+//
+// Requires basic authentication and that the authenticated user is a Grafana Admin.
+//
+// Responses:
+// 201: createServiceAccountResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 403: forbiddenError
+// 500: internalServerError
 func (api *ServiceAccountsAPI) CreateServiceAccount(c *models.ReqContext) response.Response {
 	cmd := serviceaccounts.CreateServiceAccountForm{}
 	if err := web.Bind(c.Req, &cmd); err != nil {
@@ -117,7 +131,20 @@ func (api *ServiceAccountsAPI) CreateServiceAccount(c *models.ReqContext) respon
 	return response.JSON(http.StatusCreated, serviceAccount)
 }

-// GET /api/serviceaccounts/:serviceAccountId
+// swagger:route GET /serviceaccounts/{serviceAccountId} service_accounts retrieveServiceAccount
+//
+// Get single serviceaccount by Id
+//
+// Required permissions (See note in the [introduction](https://grafana.com/docs/grafana/latest/developers/http_api/serviceaccount/#service-account-api) for an explanation):
+// action: `serviceaccounts:read` scope: `serviceaccounts:id:1` (single service account)
+//
+// Responses:
+// 200: retrieveServiceAccountResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (api *ServiceAccountsAPI) RetrieveServiceAccount(ctx *models.ReqContext) response.Response {
 	scopeID, err := strconv.ParseInt(web.Params(ctx.Req)[":serviceAccountId"], 10, 64)
 	if err != nil {
@@ -148,7 +175,20 @@ func (api *ServiceAccountsAPI) RetrieveServiceAccount(ctx *models.ReqContext) re
 	return response.JSON(http.StatusOK, serviceAccount)
 }

-// PATCH /api/serviceaccounts/:serviceAccountId
+// swagger:route PATCH /serviceaccounts/{serviceAccountId} service_accounts updateServiceAccount
+//
+// Update service account
+//
+// Required permissions (See note in the [introduction](https://grafana.com/docs/grafana/latest/developers/http_api/serviceaccount/#service-account-api) for an explanation):
+// action: `serviceaccounts:write` scope: `serviceaccounts:id:1` (single service account)
+//
+// Responses:
+// 200: updateServiceAccountResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (api *ServiceAccountsAPI) UpdateServiceAccount(c *models.ReqContext) response.Response {
 	scopeID, err := strconv.ParseInt(web.Params(c.Req)[":serviceAccountId"], 10, 64)
 	if err != nil {
@@ -204,7 +244,19 @@ func (api *ServiceAccountsAPI) validateRole(r *models.RoleType, orgRole *models.
 	return nil
 }

-// DELETE /api/serviceaccounts/:serviceAccountId
+// swagger:route DELETE /serviceaccounts/{serviceAccountId} service_accounts deleteServiceAccount
+//
+// Delete service account
+//
+// Required permissions (See note in the [introduction](https://grafana.com/docs/grafana/latest/developers/http_api/serviceaccount/#service-account-api) for an explanation):
+// action: `serviceaccounts:delete` scope: `serviceaccounts:id:1` (single service account)
+//
+// Responses:
+// 200: okResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 403: forbiddenError
+// 500: internalServerError
 func (api *ServiceAccountsAPI) DeleteServiceAccount(ctx *models.ReqContext) response.Response {
 	scopeID, err := strconv.ParseInt(web.Params(ctx.Req)[":serviceAccountId"], 10, 64)
 	if err != nil {
@@ -217,8 +269,18 @@ func (api *ServiceAccountsAPI) DeleteServiceAccount(ctx *models.ReqContext) resp
 	return response.Success("Service account deleted")
 }

-// SearchOrgServiceAccountsWithPaging is an HTTP handler to search for org users with paging.
-// GET /api/serviceaccounts/search
+// swagger:route GET /serviceaccounts/search service_accounts searchOrgServiceAccountsWithPaging
+//
+// Search service accounts with paging
+//
+// Required permissions (See note in the [introduction](https://grafana.com/docs/grafana/latest/developers/http_api/serviceaccount/#service-account-api) for an explanation):
+// action: `serviceaccounts:read` scope: `serviceaccounts:*`
+//
+// Responses:
+// 200: searchOrgServiceAccountsWithPagingResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 500: internalServerError
 func (api *ServiceAccountsAPI) SearchOrgServiceAccountsWithPaging(c *models.ReqContext) response.Response {
 	ctx := c.Req.Context()
 	perPage := c.QueryInt("perpage")
@@ -336,3 +398,81 @@ func (api *ServiceAccountsAPI) getAccessControlMetadata(c *models.ReqContext, sa

 	return accesscontrol.GetResourcesMetadata(c.Req.Context(), permissions, "serviceaccounts:id:", saIDs)
 }
+
+// swagger:parameters searchOrgServiceAccountsWithPaging
+type SearchOrgServiceAccountsWithPagingParams struct {
+	// in:query
+	// required:false
+	Disabled bool `jsson:"disabled"`
+	// in:query
+	// required:false
+	ExpiredTokens bool `json:"expiredTokens"`
+	// It will return results where the query value is contained in one of the name.
+	// Query values with spaces need to be URL encoded.
+	// in:query
+	// required:false
+	Query string `json:"query"`
+	// The default value is 1000.
+	// in:query
+	// required:false
+	PerPage int `json:"perpage"`
+	// The default value is 1.
+	// in:query
+	// required:false
+	Page int `json:"page"`
+}
+
+// swagger:parameters createServiceAccount
+type CreateServiceAccountParams struct {
+	//in:body
+	Body serviceaccounts.CreateServiceAccountForm
+}
+
+// swagger:parameters retrieveServiceAccount
+type RetrieveServiceAccountParams struct {
+	// in:path
+	ServiceAccountId int64 `json:"serviceAccountId"`
+}
+
+// swagger:parameters updateServiceAccount
+type UpdateServiceAccountParams struct {
+	// in:path
+	ServiceAccountId int64 `json:"serviceAccountId"`
+	// in:body
+	Body serviceaccounts.UpdateServiceAccountForm
+}
+
+// swagger:parameters deleteServiceAccount
+type DeleteServiceAccountParams struct {
+	// in:path
+	ServiceAccountId int64 `json:"serviceAccountId"`
+}
+
+// swagger:response searchOrgServiceAccountsWithPagingResponse
+type SearchOrgServiceAccountsWithPagingResponse struct {
+	// in:body
+	Body *serviceaccounts.SearchServiceAccountsResult
+}
+
+// swagger:response createServiceAccountResponse
+type CreateServiceAccountResponse struct {
+	// in:body
+	Body *serviceaccounts.ServiceAccountDTO
+}
+
+// swagger:response retrieveServiceAccountResponse
+type RetrieveServiceAccountResponse struct {
+	// in:body
+	Body *serviceaccounts.ServiceAccountDTO
+}
+
+// swagger:response updateServiceAccountResponse
+type UpdateServiceAccountResponse struct {
+	// in:body
+	Body struct {
+		Message        string                                    `json:"message"`
+		ID             int64                                     `json:"id"`
+		Name           string                                    `json:"name"`
+		ServiceAccount *serviceaccounts.ServiceAccountProfileDTO `json:"serviceaccount"`
+	}
+}
--- a/pkg/services/serviceaccounts/api/token.go
+++ b/pkg/services/serviceaccounts/api/token.go
@@ -48,7 +48,21 @@ func hasExpired(expiration *int64) bool {

 const sevenDaysAhead = 7 * 24 * time.Hour

-// GET /api/serviceaccounts/:serviceAccountId/tokens
+// swagger:route GET /serviceaccounts/{serviceAccountId}/tokens service_accounts listTokens
+//
+// Get service account tokens
+//
+// Required permissions (See note in the [introduction](https://grafana.com/docs/grafana/latest/developers/http_api/serviceaccount/#service-account-api) for an explanation):
+// action: `serviceaccounts:read` scope: `global:serviceaccounts:id:1` (single service account)
+//
+// Requires basic authentication and that the authenticated user is a Grafana Admin.
+//
+// Responses:
+// 200: listTokensResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 403: forbiddenError
+// 500: internalServerError
 func (api *ServiceAccountsAPI) ListTokens(ctx *models.ReqContext) response.Response {
 	saID, err := strconv.ParseInt(web.Params(ctx.Req)[":serviceAccountId"], 10, 64)
 	if err != nil {
@@ -88,8 +102,21 @@ func (api *ServiceAccountsAPI) ListTokens(ctx *models.ReqContext) response.Respo
 	return response.JSON(http.StatusOK, result)
 }

+// swagger:route POST /serviceaccounts/{serviceAccountId}/tokens service_accounts createToken
+//
 // CreateNewToken adds a token to a service account
-// POST /api/serviceaccounts/:serviceAccountId/tokens
+//
+// Required permissions (See note in the [introduction](https://grafana.com/docs/grafana/latest/developers/http_api/serviceaccount/#service-account-api) for an explanation):
+// action: `serviceaccounts:write` scope: `serviceaccounts:id:1` (single service account)
+//
+// Responses:
+// 200: createTokenResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 409: conflictError
+// 500: internalServerError
 func (api *ServiceAccountsAPI) CreateToken(c *models.ReqContext) response.Response {
 	saID, err := strconv.ParseInt(web.Params(c.Req)[":serviceAccountId"], 10, 64)
 	if err != nil {
@@ -149,8 +176,22 @@ func (api *ServiceAccountsAPI) CreateToken(c *models.ReqContext) response.Respon
 	return response.JSON(http.StatusOK, result)
 }

+// swagger:route DELETE /serviceaccounts/{serviceAccountId}/tokens/{tokenId} service_accounts deleteToken
+//
 // DeleteToken deletes service account tokens
-// DELETE /api/serviceaccounts/:serviceAccountId/tokens/:tokenId
+//
+// Required permissions (See note in the [introduction](https://grafana.com/docs/grafana/latest/developers/http_api/serviceaccount/#service-account-api) for an explanation):
+// action: `serviceaccounts:write` scope: `serviceaccounts:id:1` (single service account)
+//
+// Requires basic authentication and that the authenticated user is a Grafana Admin.
+//
+// Responses:
+// 200: okResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (api *ServiceAccountsAPI) DeleteToken(c *models.ReqContext) response.Response {
 	saID, err := strconv.ParseInt(web.Params(c.Req)[":serviceAccountId"], 10, 64)
 	if err != nil {
@@ -185,3 +226,37 @@ func (api *ServiceAccountsAPI) DeleteToken(c *models.ReqContext) response.Respon

 	return response.Success("Service account token deleted")
 }
+
+// swagger:parameters listTokens
+type ListTokensParams struct {
+	// in:path
+	ServiceAccountId int64 `json:"serviceAccountId"`
+}
+
+// swagger:parameters createToken
+type CreateTokenParams struct {
+	// in:path
+	ServiceAccountId int64 `json:"serviceAccountId"`
+	// in:body
+	Body serviceaccounts.AddServiceAccountTokenCommand
+}
+
+// swagger:parameters deleteToken
+type DeleteTokenParams struct {
+	// in:path
+	TokenId int64 `json:"tokenId"`
+	// in:path
+	ServiceAccountId int64 `json:"serviceAccountId"`
+}
+
+// swagger:response listTokensResponse
+type ListTokensResponse struct {
+	// in:body
+	Body *TokenDTO
+}
+
+// swagger:response createTokenResponse
+type CreateTokenResponse struct {
+	// in:body
+	Body *dtos.NewApiKeyResult
+}