[HTTP/OAS] Add descriptions for role management APIs (#184265)

Co-authored-by: Aleh Zasypkin <aleh.zasypkin@elastic.co>

x-pack/plugins/security/server/routes/authorization/roles/delete.ts

@@ -15,6 +15,9 @@ export function defineDeleteRolesRoutes({ router }: RouteDefinitionParams) {
   router.delete(
     {
       path: '/api/security/role/{name}',
+      options: {
+        description: `Delete a role`,
+      },
       validate: {
         params: schema.object({ name: schema.string({ minLength: 1 }) }),
       },

x-pack/plugins/security/server/routes/authorization/roles/get.ts

@@ -21,6 +21,9 @@ export function defineGetRolesRoutes({
   router.get(
     {
       path: '/api/security/role/{name}',
+      options: {
+        description: `Get a role`,
+      },
       validate: {
         params: schema.object({ name: schema.string({ minLength: 1 }) }),
       },

x-pack/plugins/security/server/routes/authorization/roles/get_all.ts

@@ -19,7 +19,13 @@ export function defineGetAllRolesRoutes({
   config,
 }: RouteDefinitionParams) {
   router.get(
-    { path: '/api/security/role', validate: false },
+    {
+      path: '/api/security/role',
+      options: {
+        description: `Get all roles`,
+      },
+      validate: false,
+    },
     createLicensedRouteHandler(async (context, request, response) => {
       try {
         const hideReservedRoles = buildFlavor === 'serverless';

x-pack/plugins/security/server/routes/authorization/roles/put.ts

@@ -45,6 +45,9 @@ export function definePutRolesRoutes({
   router.put(
     {
       path: '/api/security/role/{name}',
+      options: {
+        description: `Create or update a role`,
+      },
       validate: {
         params: schema.object({ name: schema.string({ minLength: 1, maxLength: 1024 }) }),
         query: schema.object({ createOnly: schema.boolean({ defaultValue: false }) }),

x-pack/plugins/security/server/routes/session_management/invalidate.test.ts

@@ -43,7 +43,10 @@ describe('Invalidate sessions routes', () => {
     });
 
     it('correctly defines route.', () => {
-      expect(routeConfig.options).toEqual({ tags: ['access:sessionManagement'] });
+      expect(routeConfig.options).toEqual({
+        description: 'Invalidate user sessions',
+        tags: ['access:sessionManagement'],
+      });
 
       const bodySchema = (routeConfig.validate as any).body as ObjectType;
       expect(() => bodySchema.validate({})).toThrowErrorMatchingInlineSnapshot(

x-pack/plugins/security/server/routes/session_management/invalidate.ts

@@ -33,7 +33,10 @@ export function defineInvalidateSessionsRoutes({ router, getSession }: RouteDefi
           ),
         }),
       },
-      options: { tags: ['access:sessionManagement'] },
+      options: {
+        tags: ['access:sessionManagement'],
+        description: `Invalidate user sessions`,
+      },
     },
     async (_context, request, response) => {
       return response.ok({