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

2026-08-19 01:34:54 -05:00 · 2022-07-27 09:54:37 -04:00
parent c968b76279
commit 7ba076de10
76 changed files with 6022 additions and 6161 deletions
@@ -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"`
+	}
+}
@@ -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
+}