[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)](https://github.com/elastic/kibana/pull/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 <siddharthmantri1@gmail.com>"}}]}] BACKPORT--> --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
2025-04-24 17:59:23 -04:00 · 2024-11-04 22:04:16 +01:00 · 2024-11-04 22:04:16 +01:00 · c450a850ec
commit c450a850ec
parent c8c85045ed
6 changed files with 45 additions and 15 deletions
--- 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].'
      );
    }
  });
--- 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()}`;
 };
--- 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].'
    );
  });
 });
--- 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
--- 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: [
    {
--- 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