docs(openapi): Cleanup tag usage and minor fixes (#105546)

* docs(openapi): Cleanup tag usage and minor fixes

* Add missing change

* More fixes

* make swagger-gen

* Remove unused documentation

* Update pkg/services/publicdashboards/api/query.go

Co-authored-by: Artur Wierzbicki <artur@arturwierzbicki.com>

* Run make swagger-gen

* Run make openapi3-gen

---------

Co-authored-by: Artur Wierzbicki <artur@arturwierzbicki.com>
This commit is contained in:
Thomas Casteleyn
2025-08-28 01:51:04 +04:00
committed by GitHub
co-authored by Artur Wierzbicki
parent 76b1e5e389
commit 7768e507da
18 changed files with 269 additions and 189 deletions
+10 -10
View File
@@ -345,7 +345,7 @@ func (hs *HTTPServer) getDashboardHelper(ctx context.Context, orgID int64, id in
return queryResult, nil
}
// DeleteDashboardByUID swagger:route DELETE /dashboards/uid/{uid} dashboards deleteDashboardByUID
// swagger:route DELETE /dashboards/uid/{uid} dashboards deleteDashboardByUID
//
// Delete dashboard by uid.
//
@@ -658,11 +658,11 @@ func (hs *HTTPServer) addGettingStartedPanelToHomeDashboard(c *contextmodel.ReqC
dash.Set("panels", panels)
}
// swagger:route GET /dashboards/id/{DashboardID}/versions dashboard_versions getDashboardVersionsByID
// swagger:route GET /dashboards/id/{DashboardID}/versions dashboards versions getDashboardVersionsByID
//
// Gets all existing versions for the dashboard.
//
// Please refer to [updated API](#/dashboard_versions/getDashboardVersionsByUID) instead
// Please refer to [updated API](#/dashboards/getDashboardVersionsByUID) instead
//
// Deprecated: true
//
@@ -673,7 +673,7 @@ func (hs *HTTPServer) addGettingStartedPanelToHomeDashboard(c *contextmodel.ReqC
// 404: notFoundError
// 500: internalServerError
// swagger:route GET /dashboards/uid/{uid}/versions dashboard_versions getDashboardVersionsByUID
// swagger:route GET /dashboards/uid/{uid}/versions dashboards versions getDashboardVersionsByUID
//
// Gets all existing versions for the dashboard using UID.
//
@@ -768,11 +768,11 @@ func (hs *HTTPServer) GetDashboardVersions(c *contextmodel.ReqContext) response.
})
}
// swagger:route GET /dashboards/id/{DashboardID}/versions/{DashboardVersionID} dashboard_versions getDashboardVersionByID
// swagger:route GET /dashboards/id/{DashboardID}/versions/{DashboardVersionID} dashboards versions getDashboardVersionByID
//
// Get a specific dashboard version.
//
// Please refer to [updated API](#/dashboard_versions/getDashboardVersionByUID) instead
// Please refer to [updated API](#/dashboards/getDashboardVersionByUID) instead
//
// Deprecated: true
//
@@ -783,7 +783,7 @@ func (hs *HTTPServer) GetDashboardVersions(c *contextmodel.ReqContext) response.
// 404: notFoundError
// 500: internalServerError
// swagger:route GET /dashboards/uid/{uid}/versions/{DashboardVersionID} dashboard_versions getDashboardVersionByUID
// swagger:route GET /dashboards/uid/{uid}/versions/{DashboardVersionID} dashboards versions getDashboardVersionByUID
//
// Get a specific dashboard version using UID.
//
@@ -949,11 +949,11 @@ func (hs *HTTPServer) CalculateDashboardDiff(c *contextmodel.ReqContext) respons
return response.Respond(http.StatusOK, result.Delta).SetHeader("Content-Type", "text/html")
}
// swagger:route POST /dashboards/id/{DashboardID}/restore dashboard_versions restoreDashboardVersionByID
// swagger:route POST /dashboards/id/{DashboardID}/restore dashboards versions restoreDashboardVersionByID
//
// Restore a dashboard to a given dashboard version.
//
// Please refer to [updated API](#/dashboard_versions/restoreDashboardVersionByUID) instead
// Please refer to [updated API](#/dashboards/restoreDashboardVersionByUID) instead
//
// Deprecated: true
//
@@ -964,7 +964,7 @@ func (hs *HTTPServer) CalculateDashboardDiff(c *contextmodel.ReqContext) respons
// 404: notFoundError
// 500: internalServerError
// swagger:route POST /dashboards/uid/{uid}/restore dashboard_versions restoreDashboardVersionByUID
// swagger:route POST /dashboards/uid/{uid}/restore dashboards versions restoreDashboardVersionByUID
//
// Restore a dashboard to a given dashboard version using UID.
//
+6 -6
View File
@@ -18,7 +18,7 @@ import (
"github.com/grafana/grafana/pkg/web"
)
// swagger:route GET /dashboards/uid/{uid}/permissions dashboard_permissions getDashboardPermissionsListByUID
// swagger:route GET /dashboards/uid/{uid}/permissions dashboards permissions getDashboardPermissionsListByUID
//
// Gets all existing permissions for the given dashboard.
//
@@ -29,11 +29,11 @@ import (
// 404: notFoundError
// 500: internalServerError
// swagger:route GET /dashboards/id/{DashboardID}/permissions dashboard_permissions getDashboardPermissionsListByID
// swagger:route GET /dashboards/id/{DashboardID}/permissions dashboards permissions getDashboardPermissionsListByID
//
// Gets all existing permissions for the given dashboard.
//
// Please refer to [updated API](#/dashboard_permissions/getDashboardPermissionsListByUID) instead
// Please refer to [updated API](#/dashboards/getDashboardPermissionsListByUID) instead
//
// Deprecated: true
//
@@ -89,7 +89,7 @@ func (hs *HTTPServer) GetDashboardPermissionList(c *contextmodel.ReqContext) res
return response.JSON(http.StatusOK, filteredACLs)
}
// swagger:route POST /dashboards/uid/{uid}/permissions dashboard_permissions updateDashboardPermissionsByUID
// swagger:route POST /dashboards/uid/{uid}/permissions dashboards permissions updateDashboardPermissionsByUID
//
// Updates permissions for a dashboard.
//
@@ -103,11 +103,11 @@ func (hs *HTTPServer) GetDashboardPermissionList(c *contextmodel.ReqContext) res
// 404: notFoundError
// 500: internalServerError
// swagger:route POST /dashboards/id/{DashboardID}/permissions dashboard_permissions updateDashboardPermissionsByID
// swagger:route POST /dashboards/id/{DashboardID}/permissions dashboards permissions updateDashboardPermissionsByID
//
// Updates permissions for a dashboard.
//
// Please refer to [updated API](#/dashboard_permissions/updateDashboardPermissionsByUID) instead
// Please refer to [updated API](#/dashboards/updateDashboardPermissionsByUID) instead
//
// This operation will remove existing permissions if they’re not included in the request.
//
+5 -5
View File
@@ -57,7 +57,7 @@ func (hs *HTTPServer) GetSharingOptions(c *contextmodel.ReqContext) {
})
}
// swagger:route POST /snapshots snapshots createDashboardSnapshot
// swagger:route POST /snapshots dashboards snapshots createDashboardSnapshot
//
// When creating a snapshot using the API, you have to provide the full dashboard payload including the snapshot data. This endpoint is designed for the Grafana UI.
//
@@ -93,7 +93,7 @@ func (hs *HTTPServer) CreateDashboardSnapshot(c *contextmodel.ReqContext) {
}
// GET /api/snapshots/:key
// swagger:route GET /snapshots/{key} snapshots getDashboardSnapshot
// swagger:route GET /snapshots/{key} dashboards snapshots getDashboardSnapshot
//
// Get Snapshot by Key.
//
@@ -142,7 +142,7 @@ func (hs *HTTPServer) GetDashboardSnapshot(c *contextmodel.ReqContext) response.
return response.JSON(http.StatusOK, dto).SetHeader("Cache-Control", "public, max-age=3600")
}
// swagger:route GET /snapshots-delete/{deleteKey} snapshots deleteDashboardSnapshotByDeleteKey
// swagger:route GET /snapshots-delete/{deleteKey} dashboards snapshots deleteDashboardSnapshotByDeleteKey
//
// Delete Snapshot by deleteKey.
//
@@ -178,7 +178,7 @@ func (hs *HTTPServer) DeleteDashboardSnapshotByDeleteKey(c *contextmodel.ReqCont
})
}
// swagger:route DELETE /snapshots/{key} snapshots deleteDashboardSnapshot
// swagger:route DELETE /snapshots/{key} dashboards snapshots deleteDashboardSnapshot
//
// Delete Snapshot by Key.
//
@@ -250,7 +250,7 @@ func (hs *HTTPServer) DeleteDashboardSnapshot(c *contextmodel.ReqContext) respon
})
}
// swagger:route GET /dashboard/snapshots snapshots searchDashboardSnapshots
// swagger:route GET /dashboard/snapshots dashboards snapshots searchDashboardSnapshots
//
// List snapshots.
//
+2 -2
View File
@@ -754,7 +754,7 @@ func (hs *HTTPServer) convertModelToDtos(ctx context.Context, ds *datasources.Da
return dto
}
// swagger:route GET /datasources/uid/{uid}/health datasources checkDatasourceHealthWithUID
// swagger:route GET /datasources/uid/{uid}/health datasources health checkDatasourceHealthWithUID
//
// Sends a health check request to the plugin datasource identified by the UID.
//
@@ -780,7 +780,7 @@ func (hs *HTTPServer) CheckDatasourceHealthWithUID(c *contextmodel.ReqContext) r
return hs.checkDatasourceHealth(c, ds)
}
// swagger:route GET /datasources/{id}/health datasources checkDatasourceHealthByID
// swagger:route GET /datasources/{id}/health datasources health checkDatasourceHealthByID
//
// Sends a health check request to the plugin datasource identified by the ID.
//
+1 -1
View File
@@ -51,7 +51,7 @@ func (hs *HTTPServer) getDSQueryEndpoint() web.Handler {
}
// QueryMetricsV2 returns query metrics.
// swagger:route POST /ds/query ds queryMetricsWithExpressions
// swagger:route POST /ds/query datasources queryMetricsWithExpressions
//
// DataSource query metrics with expressions.
//
+2 -2
View File
@@ -18,7 +18,7 @@ import (
"github.com/grafana/grafana/pkg/web"
)
// swagger:route GET /folders/{folder_uid}/permissions folder_permissions getFolderPermissionList
// swagger:route GET /folders/{folder_uid}/permissions folders permissions getFolderPermissionList
//
// Gets all existing permissions for the folder with the given `uid`.
//
@@ -67,7 +67,7 @@ func (hs *HTTPServer) GetFolderPermissionList(c *contextmodel.ReqContext) respon
return response.JSON(http.StatusOK, filteredACLs)
}
// swagger:route POST /folders/{folder_uid}/permissions folder_permissions updateFolderPermissions
// swagger:route POST /folders/{folder_uid}/permissions folders permissions updateFolderPermissions
//
// Updates permissions for a folder. This operation will remove existing permissions if they’re not included in the request.
//
+1 -1
View File
@@ -51,7 +51,7 @@ func (hs *HTTPServer) GetOrgByID(c *contextmodel.ReqContext) response.Response {
// swagger:route GET /orgs/name/{org_name} orgs getOrgByName
//
// Get Organization by ID.
// Get Organization by Name.
//
// Security:
// - basic:
+3 -3
View File
@@ -24,7 +24,7 @@ import (
"github.com/grafana/grafana/pkg/web"
)
// swagger:route GET /org/invites org_invites getPendingOrgInvites
// swagger:route GET /org/invites org invites getPendingOrgInvites
//
// Get pending invites.
//
@@ -48,7 +48,7 @@ func (hs *HTTPServer) GetPendingOrgInvites(c *contextmodel.ReqContext) response.
return response.JSON(http.StatusOK, queryResult)
}
// swagger:route POST /org/invites org_invites addOrgInvite
// swagger:route POST /org/invites org invites addOrgInvite
//
// Add invite.
//
@@ -184,7 +184,7 @@ func (hs *HTTPServer) inviteExistingUserToOrg(c *contextmodel.ReqContext, user *
})
}
// swagger:route DELETE /org/invites/{invitation_code}/revoke org_invites revokeInvite
// swagger:route DELETE /org/invites/{invitation_code}/revoke org invites revokeInvite
//
// Revoke invite.
//
+6 -6
View File
@@ -63,7 +63,7 @@ func (hs *HTTPServer) SetHomeDashboard(c *contextmodel.ReqContext) response.Resp
return response.Success("Home dashboard set")
}
// swagger:route GET /user/preferences user_preferences getUserPreferences
// swagger:route GET /user/preferences signed_in_user preferences getUserPreferences
//
// Get user preferences.
//
@@ -80,7 +80,7 @@ func (hs *HTTPServer) GetUserPreferences(c *contextmodel.ReqContext) response.Re
return prefapi.GetPreferencesFor(c.Req.Context(), hs.DashboardService, hs.preferenceService, hs.Features, c.GetOrgID(), userID, 0)
}
// swagger:route PUT /user/preferences user_preferences updateUserPreferences
// swagger:route PUT /user/preferences signed_in_user preferences updateUserPreferences
//
// Update user preferences.
//
@@ -106,7 +106,7 @@ func (hs *HTTPServer) UpdateUserPreferences(c *contextmodel.ReqContext) response
hs.preferenceService, hs.Features, c.GetOrgID(), userID, 0, &dtoCmd)
}
// swagger:route PATCH /user/preferences user_preferences patchUserPreferences
// swagger:route PATCH /user/preferences signed_in_user preferences patchUserPreferences
//
// Patch user preferences.
//
@@ -185,7 +185,7 @@ func (hs *HTTPServer) patchPreferencesFor(ctx context.Context, orgID, userID, te
return response.Success("Preferences updated")
}
// swagger:route GET /org/preferences org_preferences getOrgPreferences
// swagger:route GET /org/preferences org preferences getOrgPreferences
//
// Get Current Org Prefs.
//
@@ -198,7 +198,7 @@ func (hs *HTTPServer) GetOrgPreferences(c *contextmodel.ReqContext) response.Res
return prefapi.GetPreferencesFor(c.Req.Context(), hs.DashboardService, hs.preferenceService, hs.Features, c.GetOrgID(), 0, 0)
}
// swagger:route PUT /org/preferences org_preferences updateOrgPreferences
// swagger:route PUT /org/preferences org preferences updateOrgPreferences
//
// Update Current Org Prefs.
//
@@ -217,7 +217,7 @@ func (hs *HTTPServer) UpdateOrgPreferences(c *contextmodel.ReqContext) response.
return prefapi.UpdatePreferencesFor(c.Req.Context(), hs.DashboardService, hs.preferenceService, hs.Features, c.GetOrgID(), 0, 0, &dtoCmd)
}
// swagger:route PATCH /org/preferences org_preferences patchOrgPreferences
// swagger:route PATCH /org/preferences org preferences patchOrgPreferences
//
// Patch Current Org Prefs.
//
+6 -6
View File
@@ -10,7 +10,7 @@ import (
"github.com/grafana/grafana/pkg/web"
)
// swagger:route GET /org/quotas getCurrentOrg getCurrentOrgQuota
// swagger:route GET /org/quotas quota org getCurrentOrgQuota
//
// Fetch Organization quota.
//
@@ -26,7 +26,7 @@ func (hs *HTTPServer) GetCurrentOrgQuotas(c *contextmodel.ReqContext) response.R
return hs.getOrgQuotasHelper(c, c.GetOrgID())
}
// swagger:route GET /orgs/{org_id}/quotas orgs getOrgQuota
// swagger:route GET /orgs/{org_id}/quotas quota orgs getOrgQuota
//
// Fetch Organization quota.
//
@@ -56,7 +56,7 @@ func (hs *HTTPServer) getOrgQuotasHelper(c *contextmodel.ReqContext, orgID int64
return response.JSON(http.StatusOK, q)
}
// swagger:route PUT /orgs/{org_id}/quotas/{quota_target} orgs updateOrgQuota
// swagger:route PUT /orgs/{org_id}/quotas/{quota_target} quota orgs updateOrgQuota
//
// Update user quota.
//
@@ -91,7 +91,7 @@ func (hs *HTTPServer) UpdateOrgQuota(c *contextmodel.ReqContext) response.Respon
return response.Success("Organization quota updated")
}
// swagger:route GET /admin/users/{user_id}/quotas admin_users getUserQuota
// swagger:route GET /admin/users/{user_id}/quotas quota admin_users getUserQuota
//
// Fetch user quota.
//
@@ -107,7 +107,7 @@ func (hs *HTTPServer) UpdateOrgQuota(c *contextmodel.ReqContext) response.Respon
// 404: notFoundError
// 500: internalServerError
// swagger:route GET /user/quotas signed_in_user getUserQuotas
// swagger:route GET /user/quotas quota signed_in_user getUserQuotas
//
// Fetch user quota.
//
@@ -133,7 +133,7 @@ func (hs *HTTPServer) GetUserQuotas(c *contextmodel.ReqContext) response.Respons
return response.JSON(http.StatusOK, q)
}
// swagger:route PUT /admin/users/{user_id}/quotas/{quota_target} admin_users updateUserQuota
// swagger:route PUT /admin/users/{user_id}/quotas/{quota_target} quota admin_users updateUserQuota
//
// Update user quota.
//
+1 -29
View File
@@ -9,21 +9,13 @@
"description": "Folders are identified by the identifier (id) and the unique identifier (uid).\nThe identifier (id) of a folder is an auto-incrementing numeric value and is only unique per Grafana install.\nThe unique identifier (uid) of a folder can be used for uniquely identify folders between multiple Grafana installs. It’s automatically generated if not provided when creating a folder. The uid allows having consistent URLs for accessing folders and when syncing folders between multiple Grafana installs. This means that changing the title of a folder will not break any bookmarked links to that folder.\nThe uid can have a maximum length of 40 characters."
},
{
"name": "folder_permissions",
"name": "permissions",
"description": "Permissions with `folderId=-1` are the default permissions for users with the Viewer and Editor roles. Permissions can be set for a user, a team or a role (Viewer or Editor). Permissions cannot be set for Admins - they always have access to everything."
},
{
"name": "admin",
"description": "The Admin HTTP API does not currently work with an API Token. API Tokens are currently only linked to an organization and an organization role. They cannot be given the permission of server admin, only users can be given that permission. So in order to use these API calls you will have to use Basic Auth and the Grafana user must have the Grafana Admin permission. (The default admin user is called admin and has permission to use this API.)"
},
{
"name": "legacy_alerts",
"description": "You can use the Alerting API to get information about legacy dashboard alerts and their states but this API cannot be used to modify the alert. To create new alerts or modify them you need to update the dashboard JSON that contains the alerts.\nThis topic is relevant for the legacy dashboard alerts only.\nYou can find Grafana 8 alerts API specification details [here](https://editor.swagger.io/?url=https://raw.githubusercontent.com/grafana/grafana/main/pkg/services/ngalert/api/tooling/post.json)."
},
{
"name": "legacy_alerts_notification_channels",
"description": "The identifier (id) of a notification channel is an auto-incrementing numeric value and is only unique per Grafana install.\nThe unique identifier (uid) of a notification channel can be used for uniquely identify a notification channel between multiple Grafana installs. It’s automatically generated if not provided when creating a notification channel. The uid allows having consistent URLs for accessing notification channels and when syncing notification channels between multiple Grafana installations, refer to alert notification channel provisioning.\nThe uid can have a maximum length of 40 characters."
},
{
"name": "annotations",
"description": "Grafana Annotations feature released in Grafana 4.6. Annotations are saved in the Grafana database (sqlite, mysql or postgres). Annotations can be organization annotations that can be shown on any dashboard by configuring an annotation data source - they are filtered by tags. Or they can be tied to a panel on a dashboard and are then only shown on that panel."
@@ -48,10 +40,6 @@
"name": "teams",
"description": "This API can be used to create/update/delete Teams and to add/remove users to Teams. All actions require that the user has the Admin role for the organization."
},
{
"name": "datasource_permissions",
"description": "This API can be used to enable, disable, list, add and remove permissions for a data source.\nPermissions can be set for a user or a team. Permissions cannot be set for Admins - they always have access to everything.\nThis is only available in Grafana Enterprise\nIf you are running Grafana Enterprise and have Fine-grained access control enabled, for some endpoints you would need to have relevant permissions. Refer to specific resources to understand what permissions are required."
},
{
"name": "enterprise",
"description": "These are only available in Grafana Enterprise"
@@ -68,22 +56,6 @@
"name": "reports",
"description": "This API allows you to interact programmatically with the Reporting feature.\nReporting is only available in Grafana Enterprise. Read more about Grafana Enterprise.\nIf you have Fine-grained access Control enabled, for some endpoints you would need to have relevant permissions. Refer to specific resources to understand what permissions are required."
},
{
"name": "alertmanager",
"description": "Grafana Alerting Alertmanager-compatible endpoints"
},
{
"name": "ruler",
"description": "Grafana Alerting endpoints for managing rules"
},
{
"name": "testing",
"description": "Grafana Alerting testing endpoints"
},
{
"name": "prometheus",
"description": "Grafana Alerting Prometheus-compatible endpoints"
},
{
"name": "service_accounts",
"description": "If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](https://grafana.com/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information."