APIs: Fix pre-processing of getApiResources & update godoc for teams endpoints (#113536)

.gitattributes

@@ -4,3 +4,6 @@
 *_gen.go linguist-generated
 **/openapi_snapshots/*.json linguist-generated
 apps/**/pkg/apis/*_manifest.go linguist-generated
+public/openapi3.json linguist-generated
+public/api-merged.json linguist-generated
+public/api-enterprise-spec.json linguist-generated

packages/grafana-api-clients/src/clients/rtkq/advisor/v0alpha1/endpoints.gen.ts

@@ -7,7 +7,7 @@ const injectedRtkApi = api
   .injectEndpoints({
     endpoints: (build) => ({
       getApiResources: build.query<GetApiResourcesApiResponse, GetApiResourcesApiArg>({
-        query: () => ({ url: `/apis/advisor.grafana.app/v0alpha1/` }),
+        query: () => ({ url: `/` }),
         providesTags: ['API Discovery'],
       }),
       listCheck: build.query<ListCheckApiResponse, ListCheckApiArg>({

packages/grafana-api-clients/src/clients/rtkq/correlations/v0alpha1/endpoints.gen.ts

@@ -7,7 +7,7 @@ const injectedRtkApi = api
   .injectEndpoints({
     endpoints: (build) => ({
       getApiResources: build.query<GetApiResourcesApiResponse, GetApiResourcesApiArg>({
-        query: () => ({ url: `/apis/correlations.grafana.app/v0alpha1/` }),
+        query: () => ({ url: `/` }),
         providesTags: ['API Discovery'],
       }),
       listCorrelation: build.query<ListCorrelationApiResponse, ListCorrelationApiArg>({

packages/grafana-api-clients/src/clients/rtkq/dashboard/v0alpha1/endpoints.gen.ts

@@ -7,7 +7,7 @@ const injectedRtkApi = api
   .injectEndpoints({
     endpoints: (build) => ({
       getApiResources: build.query<GetApiResourcesApiResponse, GetApiResourcesApiArg>({
-        query: () => ({ url: `/apis/dashboard.grafana.app/v0alpha1/` }),
+        query: () => ({ url: `/` }),
         providesTags: ['API Discovery'],
       }),
       listDashboard: build.query<ListDashboardApiResponse, ListDashboardApiArg>({

packages/grafana-api-clients/src/clients/rtkq/folder/v1beta1/endpoints.gen.ts

@@ -7,7 +7,7 @@ const injectedRtkApi = api
   .injectEndpoints({
     endpoints: (build) => ({
       getApiResources: build.query<GetApiResourcesApiResponse, GetApiResourcesApiArg>({
-        query: () => ({ url: `/apis/folder.grafana.app/v1beta1/` }),
+        query: () => ({ url: `/` }),
         providesTags: ['API Discovery'],
       }),
       listFolder: build.query<ListFolderApiResponse, ListFolderApiArg>({

packages/grafana-api-clients/src/clients/rtkq/iam/v0alpha1/endpoints.gen.ts

@@ -16,7 +16,7 @@ const injectedRtkApi = api
   .injectEndpoints({
     endpoints: (build) => ({
       getApiResources: build.query<GetApiResourcesApiResponse, GetApiResourcesApiArg>({
-        query: () => ({ url: `/apis/iam.grafana.app/v0alpha1/` }),
+        query: () => ({ url: `/` }),
         providesTags: ['API Discovery'],
       }),
       getDisplayMapping: build.query<GetDisplayMappingApiResponse, GetDisplayMappingApiArg>({

packages/grafana-api-clients/src/clients/rtkq/legacy/endpoints.gen.ts

@@ -108,13 +108,13 @@ const injectedRtkApi = api
         query: () => ({ url: `/access-control/status` }),
         providesTags: ['access_control', 'enterprise'],
       }),
-      listTeamsRoles: build.mutation<ListTeamsRolesApiResponse, ListTeamsRolesApiArg>({
+      listTeamsRoles: build.query<ListTeamsRolesApiResponse, ListTeamsRolesApiArg>({
         query: (queryArg) => ({
           url: `/access-control/teams/roles/search`,
           method: 'POST',
           body: queryArg.rolesSearchQuery,
         }),
-        invalidatesTags: ['access_control', 'enterprise'],
+        providesTags: ['access_control', 'enterprise'],
       }),
       listTeamRoles: build.query<ListTeamRolesApiResponse, ListTeamRolesApiArg>({
         query: (queryArg) => ({ url: `/access-control/teams/${queryArg.teamId}/roles` }),
@@ -129,7 +129,11 @@ const injectedRtkApi = api
         invalidatesTags: ['access_control', 'enterprise'],
       }),
       setTeamRoles: build.mutation<SetTeamRolesApiResponse, SetTeamRolesApiArg>({
-        query: (queryArg) => ({ url: `/access-control/teams/${queryArg.teamId}/roles`, method: 'PUT' }),
+        query: (queryArg) => ({
+          url: `/access-control/teams/${queryArg.teamId}/roles`,
+          method: 'PUT',
+          body: queryArg.setTeamRolesCommand,
+        }),
         invalidatesTags: ['access_control', 'enterprise'],
       }),
       removeTeamRole: build.mutation<RemoveTeamRoleApiResponse, RemoveTeamRoleApiArg>({
@@ -1599,6 +1603,8 @@ const injectedRtkApi = api
             perpage: queryArg.perpage,
             name: queryArg.name,
             query: queryArg.query,
+            accesscontrol: queryArg.accesscontrol,
+            sort: queryArg.sort,
           },
         }),
         providesTags: ['teams'],
@@ -2142,6 +2148,7 @@ export type SetTeamRolesApiResponse =
   /** status 200 An OKResponse is returned if the request was successful. */ SuccessResponseBody;
 export type SetTeamRolesApiArg = {
   teamId: number;
+  setTeamRolesCommand: SetTeamRolesCommand;
 };
 export type RemoveTeamRoleApiResponse =
   /** status 200 An OKResponse is returned if the request was successful. */ SuccessResponseBody;
@@ -3445,6 +3452,8 @@ export type SearchTeamsApiArg = {
   name?: string;
   /** If set it will return results where the query value is contained in the name field. Query values with spaces need to be URL encoded. */
   query?: string;
+  accesscontrol?: boolean;
+  sort?: string;
 };
 export type RemoveTeamGroupApiQueryApiResponse =
   /** status 200 An OKResponse is returned if the request was successful. */ SuccessResponseBody;
@@ -3880,26 +3889,26 @@ export type ErrorResponseBody = {
     For example, a 412 Precondition Failed error may include additional information of why that error happened. */
   status?: string;
 };
-export type PermissionIsTheModelForAccessControlPermissions = {
+export type Permission = {
   action?: string;
   created?: string;
   scope?: string;
   updated?: string;
 };
 export type RoleDto = {
-  created?: string;
+  created: string;
   delegatable?: boolean;
-  description?: string;
+  description: string;
-  displayName?: string;
+  displayName: string;
   global?: boolean;
-  group?: string;
+  group: string;
   hidden?: boolean;
   mapped?: boolean;
-  name?: string;
+  name: string;
-  permissions?: PermissionIsTheModelForAccessControlPermissions[];
+  permissions?: Permission[];
-  uid?: string;
+  uid: string;
-  updated?: string;
+  updated: string;
-  version?: number;
+  version: number;
 };
 export type CreateRoleForm = {
   description?: string;
@@ -3908,7 +3917,7 @@ export type CreateRoleForm = {
   group?: string;
   hidden?: boolean;
   name?: string;
-  permissions?: PermissionIsTheModelForAccessControlPermissions[];
+  permissions?: Permission[];
   uid?: string;
   version?: number;
 };
@@ -3922,7 +3931,7 @@ export type UpdateRoleCommand = {
   group: string;
   hidden?: boolean;
   name?: string;
-  permissions?: PermissionIsTheModelForAccessControlPermissions[];
+  permissions?: Permission[];
   version?: number;
 };
 export type RoleAssignmentsDto = {
@@ -3946,6 +3955,10 @@ export type RolesSearchQuery = {
 export type AddTeamRoleCommand = {
   roleUid?: string;
 };
+export type SetTeamRolesCommand = {
+  includeHidden?: boolean;
+  roleUids?: string[];
+};
 export type AddUserRoleCommand = {
   global?: boolean;
   roleUid?: string;
@@ -6019,7 +6032,7 @@ export type CreateDashboardSnapshotCommand = {
 };
 export type CreateTeamCommand = {
   email?: string;
-  name?: string;
+  name: string;
 };
 export type TeamDto = {
   accessControl?: {
@@ -6028,13 +6041,14 @@ export type TeamDto = {
   avatarUrl?: string;
   email?: string;
   externalUID?: string;
-  id?: number;
+  /** @deprecated Use UID instead */
-  isProvisioned?: boolean;
+  id: number;
-  memberCount?: number;
+  isProvisioned: boolean;
-  name?: string;
+  memberCount: number;
-  orgId?: number;
+  name: string;
+  orgId: number;
   permission?: PermissionType;
-  uid?: string;
+  uid: string;
 };
 export type SearchTeamQueryResult = {
   page?: number;
@@ -6078,7 +6092,7 @@ export type TeamMemberDto = {
   userUID?: string;
 };
 export type AddTeamMemberCommand = {
-  userId?: number;
+  userId: number;
 };
 export type SetTeamMembershipsCommand = {
   admins?: string[];
@@ -6515,7 +6529,8 @@ export const {
   useSetRoleAssignmentsMutation,
   useGetAccessControlStatusQuery,
   useLazyGetAccessControlStatusQuery,
-  useListTeamsRolesMutation,
+  useListTeamsRolesQuery,
+  useLazyListTeamsRolesQuery,
   useListTeamRolesQuery,
   useLazyListTeamRolesQuery,
   useAddTeamRoleMutation,

packages/grafana-api-clients/src/clients/rtkq/playlist/v0alpha1/endpoints.gen.ts

@@ -7,7 +7,7 @@ const injectedRtkApi = api
   .injectEndpoints({
     endpoints: (build) => ({
       getApiResources: build.query<GetApiResourcesApiResponse, GetApiResourcesApiArg>({
-        query: () => ({ url: `/apis/playlist.grafana.app/v0alpha1/` }),
+        query: () => ({ url: `/` }),
         providesTags: ['API Discovery'],
       }),
       listPlaylist: build.query<ListPlaylistApiResponse, ListPlaylistApiArg>({

packages/grafana-api-clients/src/clients/rtkq/preferences/v1alpha1/endpoints.gen.ts

@@ -7,7 +7,7 @@ const injectedRtkApi = api
   .injectEndpoints({
     endpoints: (build) => ({
       getApiResources: build.query<GetApiResourcesApiResponse, GetApiResourcesApiArg>({
-        query: () => ({ url: `/apis/preferences.grafana.app/v1alpha1/` }),
+        query: () => ({ url: `/` }),
         providesTags: ['API Discovery'],
       }),
       listPreferences: build.query<ListPreferencesApiResponse, ListPreferencesApiArg>({

packages/grafana-api-clients/src/clients/rtkq/provisioning/v0alpha1/endpoints.gen.ts

@@ -7,7 +7,7 @@ const injectedRtkApi = api
   .injectEndpoints({
     endpoints: (build) => ({
       getApiResources: build.query<GetApiResourcesApiResponse, GetApiResourcesApiArg>({
-        query: () => ({ url: `/apis/provisioning.grafana.app/v0alpha1/` }),
+        query: () => ({ url: `/` }),
         providesTags: ['API Discovery'],
       }),
       listJob: build.query<ListJobApiResponse, ListJobApiArg>({

packages/grafana-api-clients/src/clients/rtkq/shorturl/v1beta1/endpoints.gen.ts

@@ -7,7 +7,7 @@ const injectedRtkApi = api
   .injectEndpoints({
     endpoints: (build) => ({
       getApiResources: build.query<GetApiResourcesApiResponse, GetApiResourcesApiArg>({
-        query: () => ({ url: `/apis/shorturl.grafana.app/v1beta1/` }),
+        query: () => ({ url: `/` }),
         providesTags: ['API Discovery'],
       }),
       listShortUrl: build.query<ListShortUrlApiResponse, ListShortUrlApiArg>({

packages/grafana-api-clients/src/scripts/generate-rtk-apis.ts

@@ -53,6 +53,12 @@ const config: ConfigFile = {
       tag: true,
       apiFile: '../clients/rtkq/legacy/baseAPI.ts',
       filterEndpoints: (_name, operation) => !operation.operation.deprecated,
+      endpointOverrides: [
+        {
+          pattern: 'listTeamsRoles',
+          type: 'query',
+        },
+      ],
     },
     '../clients/rtkq/migrate-to-cloud/endpoints.gen.ts': {
       schemaFile: path.join(basePath, 'public/openapi3.json'),

packages/grafana-api-clients/src/scripts/process-specs.ts

@@ -23,7 +23,7 @@ function processOpenAPISpec(spec: OpenAPIV3.Document) {
       continue;
     }
     // Remove the specified part from the path key
-    const newPathKey = path.replace(/^\/apis\/[^\/]+\/[^\/]+\/namespaces\/\{namespace}/, '');
+    const newPathKey = path.replace(/^\/apis\/[^\/]+\/[^\/]+/, '').replace(/^\/namespaces\/\{namespace}/, '');
 
     // Process each method in the path (e.g., get, post)
     const newPathItem: Record<string, unknown> = {};

pkg/services/accesscontrol/models.go

@@ -73,11 +73,17 @@ func (r Role) MarshalJSON() ([]byte, error) {
 
 // swagger:ignore
 type RoleDTO struct {
-	Version     int64        `json:"version"`
+	// required:true
-	UID         string       `xorm:"uid" json:"uid"`
+	Version int64 `json:"version"`
-	Name        string       `json:"name"`
+	// required:true
-	DisplayName string       `json:"displayName,omitempty"`
+	UID string `xorm:"uid" json:"uid"`
-	Description string       `json:"description"`
+	// required:true
+	Name string `json:"name"`
+	// required:true
+	DisplayName string `json:"displayName,omitempty"`
+	// required:true
+	Description string `json:"description"`
+	// required:true
 	Group       string       `xorm:"group_name" json:"group"`
 	Permissions []Permission `json:"permissions,omitempty"`
 	Delegatable *bool        `json:"delegatable,omitempty"`
@@ -87,7 +93,9 @@ type RoleDTO struct {
 	ID    int64 `json:"-" xorm:"pk autoincr 'id'"`
 	OrgID int64 `json:"-" xorm:"org_id"`
 
+	// required:true
 	Updated time.Time `json:"updated"`
+	// required:true
 	Created time.Time `json:"created"`
 }
 
@@ -193,7 +201,7 @@ type BuiltinRole struct {
 	Created time.Time
 }
 
-// Permission is the model for access control permissions.
+// Permission is the model for access control permissions
 type Permission struct {
 	ID     int64  `json:"-" xorm:"pk autoincr 'id'"`
 	RoleID int64  `json:"-" xorm:"role_id"`

pkg/services/team/model.go

@@ -38,6 +38,7 @@ type Team struct {
 // COMMANDS
 
 type CreateTeamCommand struct {
+	// required:true
 	Name          string `json:"name" binding:"Required"`
 	Email         string `json:"email"`
 	ExternalUID   string `json:"-"`
@@ -94,14 +95,21 @@ type SearchTeamsQuery struct {
 }
 
 type TeamDTO struct {
-	ID            int64           `json:"id" xorm:"id"`
+	// @deprecated Use UID instead
-	UID           string          `json:"uid" xorm:"uid"`
+	// required: true
-	OrgID         int64           `json:"orgId" xorm:"org_id"`
+	ID int64 `json:"id" xorm:"id"`
-	Name          string          `json:"name"`
+	// required: true
-	Email         string          `json:"email"`
+	UID string `json:"uid" xorm:"uid"`
-	ExternalUID   string          `json:"externalUID" xorm:"external_uid"`
+	// required: true
-	IsProvisioned bool            `json:"isProvisioned"`
+	OrgID int64 `json:"orgId" xorm:"org_id"`
-	AvatarURL     string          `json:"avatarUrl"`
+	// required: true
+	Name        string `json:"name"`
+	Email       string `json:"email"`
+	ExternalUID string `json:"externalUID" xorm:"external_uid"`
+	// required: true
+	IsProvisioned bool   `json:"isProvisioned"`
+	AvatarURL     string `json:"avatarUrl"`
+	// required: true
 	MemberCount   int64           `json:"memberCount"`
 	Permission    PermissionType  `json:"permission"`
 	AccessControl map[string]bool `json:"accessControl"`
@@ -146,6 +154,7 @@ type TeamMember struct {
 // COMMANDS
 
 type AddTeamMemberCommand struct {
+	// required:true
 	UserID     int64          `json:"userId" binding:"Required"`
 	Permission PermissionType `json:"-"`
 }

pkg/services/team/teamapi/team.go

@@ -344,6 +344,13 @@ type SearchTeamsParams struct {
 	// If set it will return results where the query value is contained in the name field. Query values with spaces need to be URL encoded.
 	// required:false
 	Query string `json:"query"`
+	// in:query
+	// required:false
+	// default: false
+	AccessControl bool `json:"accesscontrol"`
+	// in:query
+	// required:false
+	Sort string `json:"sort"`
 }
 
 // swagger:parameters createTeam

public/api-enterprise-spec.json

@@ -406,6 +406,14 @@
             "name": "teamId",
             "in": "path",
             "required": true
+          },
+          {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/SetTeamRolesCommand"
+            }
           }
         ],
         "responses": {
@@ -2577,6 +2585,9 @@
     },
     "AddTeamMemberCommand": {
       "type": "object",
+      "required": [
+        "userId"
+      ],
       "properties": {
         "userId": {
           "type": "integer",
@@ -3973,6 +3984,9 @@
     },
     "CreateTeamCommand": {
       "type": "object",
+      "required": [
+        "name"
+      ],
       "properties": {
         "email": {
           "type": "string"
@@ -6162,8 +6176,8 @@
       }
     },
     "Permission": {
+      "description": "Permission is the model for access control permissions",
       "type": "object",
-      "title": "Permission is the model for access control permissions.",
       "properties": {
         "action": {
           "type": "string"
@@ -7180,6 +7194,16 @@
     },
     "RoleDTO": {
       "type": "object",
+      "required": [
+        "version",
+        "uid",
+        "name",
+        "displayName",
+        "description",
+        "group",
+        "updated",
+        "created"
+      ],
       "properties": {
         "created": {
           "type": "string",
@@ -7692,6 +7716,20 @@
         }
       }
     },
+    "SetTeamRolesCommand": {
+      "type": "object",
+      "properties": {
+        "includeHidden": {
+          "type": "boolean"
+        },
+        "roleUids": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
     "SetUserRolesCommand": {
       "type": "object",
       "properties": {
@@ -7865,6 +7903,14 @@
     },
     "TeamDTO": {
       "type": "object",
+      "required": [
+        "id",
+        "uid",
+        "orgId",
+        "name",
+        "isProvisioned",
+        "memberCount"
+      ],
       "properties": {
         "accessControl": {
           "type": "object",
@@ -7882,6 +7928,7 @@
           "type": "string"
         },
         "id": {
+          "description": "@deprecated Use UID instead",
           "type": "integer",
           "format": "int64"
         },

public/api-merged.json

@@ -406,6 +406,14 @@
             "name": "teamId",
             "in": "path",
             "required": true
+          },
+          {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/SetTeamRolesCommand"
+            }
           }
         ],
         "responses": {
@@ -9931,6 +9939,17 @@
             "description": "If set it will return results where the query value is contained in the name field. Query values with spaces need to be URL encoded.",
             "name": "query",
             "in": "query"
+          },
+          {
+            "type": "boolean",
+            "default": false,
+            "name": "accesscontrol",
+            "in": "query"
+          },
+          {
+            "type": "string",
+            "name": "sort",
+            "in": "query"
           }
         ],
         "responses": {
@@ -12750,6 +12769,9 @@
     },
     "AddTeamMemberCommand": {
       "type": "object",
+      "required": [
+        "userId"
+      ],
       "properties": {
         "userId": {
           "type": "integer",
@@ -14946,6 +14968,9 @@
     },
     "CreateTeamCommand": {
       "type": "object",
+      "required": [
+        "name"
+      ],
       "properties": {
         "email": {
           "type": "string"
@@ -18651,8 +18676,8 @@
       }
     },
     "Permission": {
+      "description": "Permission is the model for access control permissions",
       "type": "object",
-      "title": "Permission is the model for access control permissions.",
       "properties": {
         "action": {
           "type": "string"
@@ -20562,6 +20587,16 @@
     },
     "RoleDTO": {
       "type": "object",
+      "required": [
+        "version",
+        "uid",
+        "name",
+        "displayName",
+        "description",
+        "group",
+        "updated",
+        "created"
+      ],
       "properties": {
         "created": {
           "type": "string",
@@ -21449,6 +21484,20 @@
         }
       }
     },
+    "SetTeamRolesCommand": {
+      "type": "object",
+      "properties": {
+        "includeHidden": {
+          "type": "boolean"
+        },
+        "roleUids": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
     "SetUserRolesCommand": {
       "type": "object",
       "properties": {
@@ -21885,6 +21934,14 @@
     },
     "TeamDTO": {
       "type": "object",
+      "required": [
+        "id",
+        "uid",
+        "orgId",
+        "name",
+        "isProvisioned",
+        "memberCount"
+      ],
       "properties": {
         "accessControl": {
           "type": "object",
@@ -21902,6 +21959,7 @@
           "type": "string"
         },
         "id": {
+          "description": "@deprecated Use UID instead",
           "type": "integer",
           "format": "int64"
         },

public/openapi3.json

@@ -2262,6 +2262,9 @@
             "type": "integer"
           }
         },
+        "required": [
+          "userId"
+        ],
         "type": "object"
       },
       "AddTeamRoleCommand": {
@@ -4460,6 +4463,9 @@
             "type": "string"
           }
         },
+        "required": [
+          "name"
+        ],
         "type": "object"
       },
       "DashboardACLInfoDTO": {
@@ -8158,6 +8164,7 @@
         "type": "object"
       },
       "Permission": {
+        "description": "Permission is the model for access control permissions",
         "properties": {
           "action": {
             "type": "string"
@@ -8174,7 +8181,6 @@
             "type": "string"
           }
         },
-        "title": "Permission is the model for access control permissions.",
         "type": "object"
       },
       "PermissionDenied": {
@@ -10115,6 +10121,16 @@
             "type": "integer"
           }
         },
+        "required": [
+          "version",
+          "uid",
+          "name",
+          "displayName",
+          "description",
+          "group",
+          "updated",
+          "created"
+        ],
         "type": "object"
       },
       "RolesSearchQuery": {
@@ -10955,6 +10971,20 @@
         },
         "type": "object"
       },
+      "SetTeamRolesCommand": {
+        "properties": {
+          "includeHidden": {
+            "type": "boolean"
+          },
+          "roleUids": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          }
+        },
+        "type": "object"
+      },
       "SetUserRolesCommand": {
         "properties": {
           "global": {
@@ -11407,6 +11437,7 @@
             "type": "string"
           },
           "id": {
+            "description": "@deprecated Use UID instead",
             "format": "int64",
             "type": "integer"
           },
@@ -11431,6 +11462,14 @@
             "type": "string"
           }
         },
+        "required": [
+          "id",
+          "uid",
+          "orgId",
+          "name",
+          "isProvisioned",
+          "memberCount"
+        ],
         "type": "object"
       },
       "TeamGroupDTO": {
@@ -14207,6 +14246,17 @@
             }
           }
         ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SetTeamRolesCommand"
+              }
+            }
+          },
+          "required": true,
+          "x-originalParamName": "body"
+        },
         "responses": {
           "200": {
             "$ref": "#/components/responses/okResponse"
@@ -24515,6 +24565,21 @@
             "schema": {
               "type": "string"
             }
+          },
+          {
+            "in": "query",
+            "name": "accesscontrol",
+            "schema": {
+              "default": false,
+              "type": "boolean"
+            }
+          },
+          {
+            "in": "query",
+            "name": "sort",
+            "schema": {
+              "type": "string"
+            }
           }
         ],
         "responses": {