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
index 8da2324e68f02..308f0a7686597 100644
--- 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
index 4cd6875913780..7979188f2641e 100644
--- 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
index 17191e7ab1b1c..2ce135a378789 100644
--- 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.
[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
index f096d2bb1ca32..f64e3266a656f 100644
--- 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 ? `
` : ''}${
+ 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
index c2eb872f1e225..83de79ea9216d 100644
--- 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.
[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
index f0c45b82d1d81..864c7c8982328 100644
--- 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 ? '
' : ''}${
+ 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