[8.16] [Authz] Fix description generation for Open API spec for an API (

#198054) (#198837) # Backport This will backport the following commits from `main` to `8.16`: - [[Authz] Fix description generation for Open API spec for an API (#198054)](#198054)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) \n\n### Questions ?\nPlease refer to the [Backport tool\ndocumentation](https://github.com/sqren/backport)\n\n\n\nCo-authored-by: Sid <[email protected]>"}}]}] BACKPORT--> --------- Co-authored-by: kibanamachine <[email protected]>
elastic · Nov 4, 2024 · c450a85 · c450a85
1 parent c8c8504
commit c450a85
Show file tree

Hide file tree

Showing 6 changed files with 45 additions and 15 deletions.
diff --git a/packages/kbn-router-to-openapispec/src/extract_authz_description.test.ts b/packages/kbn-router-to-openapispec/src/extract_authz_description.test.ts
@@ -33,7 +33,9 @@ describe('extractAuthzDescription', () => {
       },
     };
     const description = extractAuthzDescription(routeSecurity);
-    expect(description).toBe('[Authz] Route required privileges: ALL of [manage_spaces].');
+    expect(description).toBe(
+      '[Required authorization] Route required privileges: ALL of [manage_spaces].'
+    );
   });
 
   it('should return route authz description for privilege groups', () => {
@@ -44,7 +46,9 @@ describe('extractAuthzDescription', () => {
         },
       };
       const description = extractAuthzDescription(routeSecurity);
-      expect(description).toBe('[Authz] Route required privileges: ALL of [console].');
+      expect(description).toBe(
+        '[Required authorization] Route required privileges: ALL of [console].'
+      );
     }
     {
       const routeSecurity: RouteSecurity = {
@@ -58,7 +62,7 @@ describe('extractAuthzDescription', () => {
       };
       const description = extractAuthzDescription(routeSecurity);
       expect(description).toBe(
-        '[Authz] Route required privileges: ANY of [manage_spaces OR taskmanager].'
+        '[Required authorization] Route required privileges: ANY of [manage_spaces OR taskmanager].'
       );
     }
     {
@@ -74,7 +78,7 @@ describe('extractAuthzDescription', () => {
       };
       const description = extractAuthzDescription(routeSecurity);
       expect(description).toBe(
-        '[Authz] Route required privileges: ALL of [console, filesManagement] AND ANY of [manage_spaces OR taskmanager].'
+        '[Required authorization] Route required privileges: ALL of [console, filesManagement] AND ANY of [manage_spaces OR taskmanager].'
       );
     }
   });

diff --git a/packages/kbn-router-to-openapispec/src/extract_authz_description.ts b/packages/kbn-router-to-openapispec/src/extract_authz_description.ts
@@ -56,5 +56,5 @@ export const extractAuthzDescription = (routeSecurity: InternalRouteSecurity | u
     return `Route required privileges: ${getPrivilegesDescription(allRequired, anyRequired)}.`;
   };
 
-  return `[Authz] ${getDescriptionForRoute()}`;
+  return `[Required authorization] ${getDescriptionForRoute()}`;
 };
diff --git a/packages/kbn-router-to-openapispec/src/process_router.test.ts b/packages/kbn-router-to-openapispec/src/process_router.test.ts
@@ -124,6 +124,26 @@ describe('processRouter', () => {
           },
         },
       },
+      {
+        path: '/quux',
+        method: 'post',
+        options: {
+          description: 'This a test route description.',
+        },
+        handler: jest.fn(),
+        validationSchemas: { request: { body: schema.object({}) } },
+        security: {
+          authz: {
+            requiredPrivileges: [
+              'manage_spaces',
+              {
+                allRequired: ['taskmanager'],
+                anyRequired: ['console'],
+              },
+            ],
+          },
+        },
+      },
     ],
   } as unknown as Router;
 
@@ -132,7 +152,7 @@ describe('processRouter', () => {
       version: '2023-10-31',
     });
 
-    expect(Object.keys(result1.paths!)).toHaveLength(4);
+    expect(Object.keys(result1.paths!)).toHaveLength(5);
 
     const result2 = processRouter(testRouter, new OasConverter(), createOpIdGenerator(), {
       version: '2024-10-31',
@@ -148,7 +168,11 @@ describe('processRouter', () => {
     expect(result.paths['/qux']?.post).toBeDefined();
 
     expect(result.paths['/qux']?.post?.description).toEqual(
-      '[Authz] Route required privileges: ALL of [manage_spaces, taskmanager] AND ANY of [console].'
+      '[Required authorization] Route required privileges: ALL of [manage_spaces, taskmanager] AND ANY of [console].'
+    );
+
+    expect(result.paths['/quux']?.post?.description).toEqual(
+      'This a test route description.<br/><br/>[Required authorization] Route required privileges: ALL of [manage_spaces, taskmanager] AND ANY of [console].'
     );
   });
 });
diff --git a/packages/kbn-router-to-openapispec/src/process_router.ts b/packages/kbn-router-to-openapispec/src/process_router.ts
@@ -64,18 +64,19 @@ export const processRouter = (
         parameters.push(...pathObjects, ...queryObjects);
       }
 
-      let description = '';
+      let description = `${route.options.description ?? ''}`;
       if (route.security) {
         const authzDescription = extractAuthzDescription(route.security);
 
-        description = `${route.options.description ?? ''}${authzDescription ?? ''}`;
+        description += `${route.options.description && authzDescription ? `<br/><br/>` : ''}${
+          authzDescription ?? ''
+        }`;
       }
 
       const operation: CustomOperationObject = {
         summary: route.options.summary ?? '',
         tags: route.options.tags ? extractTags(route.options.tags) : [],
         ...(description ? { description } : {}),
-        ...(route.options.description ? { description: route.options.description } : {}),
         ...(route.options.deprecated ? { deprecated: route.options.deprecated } : {}),
         ...(route.options.discontinued ? { 'x-discontinued': route.options.discontinued } : {}),
         requestBody: !!validationSchemas?.body

diff --git a/packages/kbn-router-to-openapispec/src/process_versioned_router.test.ts b/packages/kbn-router-to-openapispec/src/process_versioned_router.test.ts
@@ -156,7 +156,7 @@ describe('processVersionedRouter', () => {
     expect(results.paths['/foo']!.get).toBeDefined();
 
     expect(results.paths['/foo']!.get!.description).toBe(
-      '[Authz] Route required privileges: ALL of [manage_spaces].'
+      'This is a test route description.<br/><br/>[Required authorization] Route required privileges: ALL of [manage_spaces].'
     );
   });
 });
@@ -175,6 +175,7 @@ const createTestRoute: () => any = () => ({
         requiredPrivileges: ['manage_spaces'],
       },
     },
+    description: 'This is a test route description.',
   },
   handlers: [
     {

diff --git a/packages/kbn-router-to-openapispec/src/process_versioned_router.ts b/packages/kbn-router-to-openapispec/src/process_versioned_router.ts
@@ -91,12 +91,13 @@ export const processVersionedRouter = (
           ...queryObjects,
         ];
       }
-
-      let description = '';
+      let description = `${route.options.description ?? ''}`;
       if (route.options.security) {
         const authzDescription = extractAuthzDescription(route.options.security);
 
-        description = `${route.options.description ?? ''}${authzDescription ?? ''}`;
+        description += `${route.options.description && authzDescription ? '<br/><br/>' : ''}${
+          authzDescription ?? ''
+        }`;
       }
 
       const hasBody = Boolean(extractValidationSchemaFromVersionedHandler(handler)?.request?.body);
@@ -106,7 +107,6 @@ export const processVersionedRouter = (
         summary: route.options.summary ?? '',
         tags: route.options.options?.tags ? extractTags(route.options.options.tags) : [],
         ...(description ? { description } : {}),
-        ...(route.options.description ? { description: route.options.description } : {}),
         ...(route.options.deprecated ? { deprecated: route.options.deprecated } : {}),
         ...(route.options.discontinued ? { 'x-discontinued': route.options.discontinued } : {}),
         requestBody: hasBody