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

2022-07-27 09:54:37 -04:00
parent c968b76279
commit 7ba076de10
76 changed files with 6022 additions and 6161 deletions
@@ -27,6 +27,18 @@ import (
 var datasourcesLogger = log.New("datasources")
 var secretsPluginError datasources.ErrDatasourceSecretsPluginUserFriendly

+// swagger:route GET /datasources datasources getDataSources
+//
+// Get all data sources.
+//
+// If you are running Grafana Enterprise and have Fine-grained access control enabled
+// you need to have a permission with action: `datasources:read` and scope: `datasources:*`.
+//
+// Responses:
+// 200: getDataSourcesResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 500: internalServerError
 func (hs *HTTPServer) GetDataSources(c *models.ReqContext) response.Response {
 	query := datasources.GetDataSourcesQuery{OrgId: c.OrgId, DataSourceLimit: hs.Cfg.DataSourceLimit}

@@ -73,7 +85,24 @@ func (hs *HTTPServer) GetDataSources(c *models.ReqContext) response.Response {
 	return response.JSON(http.StatusOK, &result)
 }

-// GET /api/datasources/:id
+// swagger:route GET /datasources/{id} datasources getDataSourceByID
+//
+// Get a single data source by Id.
+//
+// If you are running Grafana Enterprise and have Fine-grained access control enabled
+// you need to have a permission with action: `datasources:read` and scopes: `datasources:*`, `datasources:id:*` and `datasources:id:1` (single data source).
+//
+// Please refer to [updated API](#/datasources/getDataSourceByUID) instead
+//
+// Deprecated: true
+//
+// Responses:
+// 200: getDataSourceResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (hs *HTTPServer) GetDataSourceById(c *models.ReqContext) response.Response {
 	id, err := strconv.ParseInt(web.Params(c.Req)[":id"], 10, 64)
 	if err != nil {
@@ -102,7 +131,23 @@ func (hs *HTTPServer) GetDataSourceById(c *models.ReqContext) response.Response
 	return response.JSON(http.StatusOK, &dto)
 }

-// DELETE /api/datasources/:id
+// swagger:route DELETE /datasources/{id} datasources deleteDataSourceByID
+//
+// Delete an existing data source by id.
+//
+// If you are running Grafana Enterprise and have Fine-grained access control enabled
+// you need to have a permission with action: `datasources:delete` and scopes: `datasources:*`, `datasources:id:*` and `datasources:id:1` (single data source).
+//
+// Please refer to [updated API](#/datasources/deleteDataSourceByUID) instead
+//
+// Deprecated: true
+//
+// Responses:
+// 200: okResponse
+// 401: unauthorisedError
+// 404: notFoundError
+// 403: forbiddenError
+// 500: internalServerError
 func (hs *HTTPServer) DeleteDataSourceById(c *models.ReqContext) response.Response {
 	id, err := strconv.ParseInt(web.Params(c.Req)[":id"], 10, 64)
 	if err != nil {
@@ -140,7 +185,20 @@ func (hs *HTTPServer) DeleteDataSourceById(c *models.ReqContext) response.Respon
 	return response.Success("Data source deleted")
 }

-// GET /api/datasources/uid/:uid
+// swagger:route GET /datasources/uid/{uid} datasources getDataSourceByUID
+//
+// Get a single data source by UID.
+//
+// If you are running Grafana Enterprise and have Fine-grained access control enabled
+// you need to have a permission with action: `datasources:read` and scopes: `datasources:*`, `datasources:uid:*` and `datasources:uid:kLtEtcRGk` (single data source).
+//
+// Responses:
+// 200: getDataSourceResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (hs *HTTPServer) GetDataSourceByUID(c *models.ReqContext) response.Response {
 	ds, err := hs.getRawDataSourceByUID(c.Req.Context(), web.Params(c.Req)[":uid"], c.OrgId)

@@ -159,7 +217,19 @@ func (hs *HTTPServer) GetDataSourceByUID(c *models.ReqContext) response.Response
 	return response.JSON(http.StatusOK, &dto)
 }

-// DELETE /api/datasources/uid/:uid
+// swagger:route DELETE /datasources/uid/{uid} datasources deleteDataSourceByUID
+//
+// Delete an existing data source by UID.
+//
+// If you are running Grafana Enterprise and have Fine-grained access control enabled
+// you need to have a permission with action: `datasources:delete` and scopes: `datasources:*`, `datasources:uid:*` and `datasources:uid:kLtEtcRGk` (single data source).
+//
+// Responses:
+// 200: okResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (hs *HTTPServer) DeleteDataSourceByUID(c *models.ReqContext) response.Response {
 	uid := web.Params(c.Req)[":uid"]

@@ -197,7 +267,19 @@ func (hs *HTTPServer) DeleteDataSourceByUID(c *models.ReqContext) response.Respo
 	})
 }

-// DELETE /api/datasources/name/:name
+// swagger:route DELETE /datasources/name/{name} datasources deleteDataSourceByName
+//
+// Delete an existing data source by name.
+//
+// If you are running Grafana Enterprise and have Fine-grained access control enabled
+// you need to have a permission with action: `datasources:delete` and scopes: `datasources:*`, `datasources:name:*` and `datasources:name:test_datasource` (single data source).
+//
+// Responses:
+// 200: deleteDataSourceByNameResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (hs *HTTPServer) DeleteDataSourceByName(c *models.ReqContext) response.Response {
 	name := web.Params(c.Req)[":name"]

@@ -242,7 +324,23 @@ func validateURL(cmdType string, url string) response.Response {
 	return nil
 }

-// POST /api/datasources/
+// swagger:route POST /datasources datasources addDataSource
+//
+// Create a data source.
+//
+// By defining `password` and `basicAuthPassword` under secureJsonData property
+// Grafana encrypts them securely as an encrypted blob in the database.
+// The response then lists the encrypted fields under secureJsonFields.
+//
+// If you are running Grafana Enterprise and have Fine-grained access control enabled
+// you need to have a permission with action: `datasources:create`
+//
+// Responses:
+// 200: createOrUpdateDatasourceResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 409: conflictError
+// 500: internalServerError
 func (hs *HTTPServer) AddDataSource(c *models.ReqContext) response.Response {
 	cmd := datasources.AddDataSourceCommand{}
 	if err := web.Bind(c.Req, &cmd); err != nil {
@@ -279,7 +377,27 @@ func (hs *HTTPServer) AddDataSource(c *models.ReqContext) response.Response {
 	})
 }

-// PUT /api/datasources/:id
+// swagger:route PUT /datasources/{id} datasources updateDataSourceByID
+//
+// Update an existing data source by its sequential ID.
+//
+// Similar to creating a data source, `password` and `basicAuthPassword` should be defined under
+// secureJsonData in order to be stored securely as an encrypted blob in the database. Then, the
+// encrypted fields are listed under secureJsonFields section in the response.
+//
+// If you are running Grafana Enterprise and have Fine-grained access control enabled
+// you need to have a permission with action: `datasources:write` and scopes: `datasources:*`, `datasources:id:*` and `datasources:id:1` (single data source).
+//
+// Please refer to [updated API](#/datasources/updateDataSourceByUID) instead
+//
+// Deprecated: true
+//
+// Responses:
+// 200: createOrUpdateDatasourceResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 500: internalServerError
+
 func (hs *HTTPServer) UpdateDataSourceByID(c *models.ReqContext) response.Response {
 	cmd := datasources.UpdateDataSourceCommand{}
 	if err := web.Bind(c.Req, &cmd); err != nil {
@@ -305,7 +423,22 @@ func (hs *HTTPServer) UpdateDataSourceByID(c *models.ReqContext) response.Respon
 	return hs.updateDataSourceByID(c, ds, cmd)
 }

-// PUT /api/datasources/:uid
+// swagger:route PUT /datasources/uid/{uid} datasources updateDataSourceByUID
+//
+// Update an existing data source.
+//
+// Similar to creating a data source, `password` and `basicAuthPassword` should be defined under
+// secureJsonData in order to be stored securely as an encrypted blob in the database. Then, the
+// encrypted fields are listed under secureJsonFields section in the response.
+//
+// If you are running Grafana Enterprise and have Fine-grained access control enabled
+// you need to have a permission with action: `datasources:write` and scopes: `datasources:*`, `datasources:uid:*` and `datasources:uid:1` (single data source).
+//
+// Responses:
+// 200: createOrUpdateDatasourceResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 500: internalServerError
 func (hs *HTTPServer) UpdateDataSourceByUID(c *models.ReqContext) response.Response {
 	cmd := datasources.UpdateDataSourceCommand{}
 	if err := web.Bind(c.Req, &cmd); err != nil {
@@ -395,7 +528,18 @@ func (hs *HTTPServer) getRawDataSourceByUID(ctx context.Context, uid string, org
 	return query.Result, nil
 }

-// Get /api/datasources/name/:name
+// swagger:route GET /datasources/name/{name} datasources getDataSourceByName
+//
+// Get a single data source by Name.
+//
+// If you are running Grafana Enterprise and have Fine-grained access control enabled
+// you need to have a permission with action: `datasources:read` and scopes: `datasources:*`, `datasources:name:*` and `datasources:name:test_datasource` (single data source).
+//
+// Responses:
+// 200: getDataSourceResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 500: internalServerError
 func (hs *HTTPServer) GetDataSourceByName(c *models.ReqContext) response.Response {
 	query := datasources.GetDataSourceQuery{Name: web.Params(c.Req)[":name"], OrgId: c.OrgId}

@@ -410,7 +554,19 @@ func (hs *HTTPServer) GetDataSourceByName(c *models.ReqContext) response.Respons
 	return response.JSON(http.StatusOK, &dto)
 }

-// Get /api/datasources/id/:name
+// swagger:route GET /datasources/id/{name} datasources getDataSourceIdByName
+//
+// Get data source Id by Name.
+//
+// If you are running Grafana Enterprise and have Fine-grained access control enabled
+// you need to have a permission with action: `datasources:read` and scopes: `datasources:*`, `datasources:name:*` and `datasources:name:test_datasource` (single data source).
+//
+// Responses:
+// 200: getDataSourceIDResponse
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (hs *HTTPServer) GetDataSourceIdByName(c *models.ReqContext) response.Response {
 	query := datasources.GetDataSourceQuery{Name: web.Params(c.Req)[":name"], OrgId: c.OrgId}

@@ -429,7 +585,21 @@ func (hs *HTTPServer) GetDataSourceIdByName(c *models.ReqContext) response.Respo
 	return response.JSON(http.StatusOK, &dtos)
 }

-// /api/datasources/:id/resources/*
+// swagger:route GET /datasources/{id}/resources/{datasource_proxy_route} datasources callDatasourceResourceByID
+//
+// Fetch data source resources by Id.
+//
+// Please refer to [updated API](#/datasources/callDatasourceResourceWithUID) instead
+//
+// Deprecated: true
+//
+// Responses:
+// 200: okResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (hs *HTTPServer) CallDatasourceResource(c *models.ReqContext) {
 	datasourceID, err := strconv.ParseInt(web.Params(c.Req)[":id"], 10, 64)
 	if err != nil {
@@ -455,7 +625,17 @@ func (hs *HTTPServer) CallDatasourceResource(c *models.ReqContext) {
 	hs.callPluginResourceWithDataSource(c, plugin.ID, ds)
 }

-// /api/datasources/uid/:uid/resources/*
+// swagger:route GET /datasources/uid/{uid}/resources/{datasource_proxy_route} datasources callDatasourceResourceWithUID
+//
+// Fetch data source resources.
+//
+// Responses:
+// 200: okResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 403: forbiddenError
+// 404: notFoundError
+// 500: internalServerError
 func (hs *HTTPServer) CallDatasourceResourceWithUID(c *models.ReqContext) {
 	dsUID := web.Params(c.Req)[":uid"]
 	if !util.IsValidShortUID(dsUID) {
@@ -517,8 +697,16 @@ func (hs *HTTPServer) convertModelToDtos(ctx context.Context, ds *datasources.Da
 	return dto
 }

-// CheckDatasourceHealthWithUID sends a health check request to the plugin datasource
-// /api/datasource/uid/:uid/health
+// swagger:route GET /datasources/uid/{uid}/health datasources checkDatasourceHealthWithUID
+//
+// Sends a health check request to the plugin datasource identified by the UID.
+//
+// Responses:
+// 200: okResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 403: forbiddenError
+// 500: internalServerError
 func (hs *HTTPServer) CheckDatasourceHealthWithUID(c *models.ReqContext) response.Response {
 	dsUID := web.Params(c.Req)[":uid"]
 	if !util.IsValidShortUID(dsUID) {
@@ -535,8 +723,20 @@ func (hs *HTTPServer) CheckDatasourceHealthWithUID(c *models.ReqContext) respons
 	return hs.checkDatasourceHealth(c, ds)
 }

-// CheckDatasourceHealth sends a health check request to the plugin datasource
-// /api/datasource/:id/health
+// swagger:route GET /datasources/{id}/health datasources checkDatasourceHealthByID
+//
+// Sends a health check request to the plugin datasource identified by the ID.
+//
+// Please refer to [updated API](#/datasources/checkDatasourceHealthWithUID) instead
+//
+// Deprecated: true
+//
+// Responses:
+// 200: okResponse
+// 400: badRequestError
+// 401: unauthorisedError
+// 403: forbiddenError
+// 500: internalServerError
 func (hs *HTTPServer) CheckDatasourceHealth(c *models.ReqContext) response.Response {
 	datasourceID, err := strconv.ParseInt(web.Params(c.Req)[":id"], 10, 64)
 	if err != nil {
@@ -648,3 +848,176 @@ func (hs *HTTPServer) filterDatasourcesByQueryPermission(ctx context.Context, us

 	return query.Result, nil
 }
+
+// swagger:parameters checkDatasourceHealthByID
+type CheckDatasourceHealthByIDParams struct {
+	// in:path
+	// required:true
+	DatasourceID string `json:"id"`
+}
+
+// swagger:parameters callDatasourceResourceByID
+type CallDatasourceResourceByIDParams struct {
+	// in:path
+	// required:true
+	DatasourceID string `json:"id"`
+}
+
+// swagger:parameters deleteDataSourceByID
+type DeleteDataSourceByIDParams struct {
+	// in:path
+	// required:true
+	DatasourceID string `json:"id"`
+}
+
+// swagger:parameters getDataSourceByID
+type GetDataSourceByIDParams struct {
+	// in:path
+	// required:true
+	DatasourceID string `json:"id"`
+}
+
+// swagger:parameters checkDatasourceHealthWithUID
+type CheckDatasourceHealthWithUIDParams struct {
+	// in:path
+	// required:true
+	DatasourceUID string `json:"uid"`
+}
+
+// swagger:parameters callDatasourceResourceWithUID
+type CallDatasourceResourceWithUIDParams struct {
+	// in:path
+	// required:true
+	DatasourceUID string `json:"uid"`
+}
+
+// swagger:parameters deleteDataSourceByUID
+type DeleteDataSourceByUIDParams struct {
+	// in:path
+	// required:true
+	DatasourceUID string `json:"uid"`
+}
+
+// swagger:parameters getDataSourceByUID
+type GetDataSourceByUIDParams struct {
+	// in:path
+	// required:true
+	DatasourceUID string `json:"uid"`
+}
+
+// swagger:parameters getDataSourceByName
+type GetDataSourceByNameParams struct {
+	// in:path
+	// required:true
+	DatasourceName string `json:"name"`
+}
+
+// swagger:parameters deleteDataSourceByName
+type DeleteDataSourceByNameParams struct {
+	// in:path
+	// required:true
+	DatasourceName string `json:"name"`
+}
+
+// swagger:parameters getDataSourceIdByName
+type GetDataSourceIdByNameParams struct {
+	// in:path
+	// required:true
+	DatasourceName string `json:"name"`
+}
+
+// swagger:parameters addDataSource
+type AddDataSourceParams struct {
+	// in:body
+	// required:true
+	Body datasources.AddDataSourceCommand
+}
+
+// swagger:parameters updateDataSourceByID
+type UpdateDataSourceByIDParams struct {
+	// in:body
+	// required:true
+	Body datasources.UpdateDataSourceCommand
+	// in:path
+	// required:true
+	DatasourceID string `json:"id"`
+}
+
+// swagger:parameters updateDataSourceByUID
+type UpdateDataSourceByUIDParams struct {
+	// in:body
+	// required:true
+	Body datasources.UpdateDataSourceCommand
+	// in:path
+	// required:true
+	DatasourceUID string `json:"uid"`
+}
+
+// swagger:response getDataSourcesResponse
+type GetDataSourcesResponse struct {
+	// The response message
+	// in: body
+	Body dtos.DataSourceList `json:"body"`
+}
+
+// swagger:response getDataSourceResponse
+type GetDataSourceResponse struct {
+	// The response message
+	// in: body
+	Body dtos.DataSource `json:"body"`
+}
+
+// swagger:response createOrUpdateDatasourceResponse
+type CreateOrUpdateDatasourceResponse struct {
+	// The response message
+	// in: body
+	Body struct {
+		// ID Identifier of the new data source.
+		// required: true
+		// example: 65
+		ID int64 `json:"id"`
+
+		// Name of the new data source.
+		// required: true
+		// example: My Data source
+		Name string `json:"name"`
+
+		// Message Message of the deleted dashboard.
+		// required: true
+		// example: Data source added
+		Message string `json:"message"`
+
+		// Datasource properties
+		// required: true
+		Datasource dtos.DataSource `json:"datasource"`
+	} `json:"body"`
+}
+
+// swagger:response getDataSourceIDResponse
+type GetDataSourceIDresponse struct {
+	// The response message
+	// in: body
+	Body struct {
+		// ID Identifier of the data source.
+		// required: true
+		// example: 65
+		ID int64 `json:"id"`
+	} `json:"body"`
+}
+
+// swagger:response deleteDataSourceByNameResponse
+type DeleteDataSourceByNameResponse struct {
+	// The response message
+	// in: body
+	Body struct {
+		// ID Identifier of the deleted data source.
+		// required: true
+		// example: 65
+		ID int64 `json:"id"`
+
+		// Message Message of the deleted dashboard.
+		// required: true
+		// example: Dashboard My Dashboard deleted
+		Message string `json:"message"`
+	} `json:"body"`
+}