[Console] Add support for documentation links on Serverless

packages/kbn-generate-console-definitions/src/generate_console_definitions.ts

@@ -44,6 +44,13 @@ const generatePatterns = (endpoint: SpecificationTypes.Endpoint): string[] => {
 const generateDocumentation = (endpoint: SpecificationTypes.Endpoint): string => {
   return endpoint.docUrl;
 };
+
+const generateServerlessDocumentation = (
+  endpoint: SpecificationTypes.Endpoint
+): string | undefined => {
+  return endpoint.docUrlServerless;
+};
+
 interface GeneratedParameters {
   urlParams: DefinitionUrlParams;
   urlComponents: DefinitionUrlParams;
@@ -87,13 +94,21 @@ const generateDefinition = (
   const methods = generateMethods(endpoint);
   const patterns = generatePatterns(endpoint);
   const documentation = generateDocumentation(endpoint);
+  const documentationServerless = generateServerlessDocumentation(endpoint);
   const availability = generateAvailability(endpoint);
   let definition: EndpointDescription = {};
   const params = generateParameters(endpoint, schema);
   if (params) {
     definition = addParams(definition, params);
   }
-  definition = { ...definition, methods, patterns, documentation, availability };
+  definition = {
+    ...definition,
+    methods,
+    patterns,
+    documentation,
+    documentation_serverless: documentationServerless,
+    availability,
+  };
 
   return definition;
 };

packages/kbn-generate-console-definitions/src/types/specification_types.ts

@@ -411,6 +411,11 @@ export interface Endpoint {
   name: string;
   description: string;
   docUrl: string;
+  /**
+   * Optional serverless-specific documentation URL.
+   * When present, Console can prefer this for serverless deployments.
+   */
+  docUrlServerless?: string;
   docId?: string;
   deprecation?: Deprecation;
   availability: Availabilities;

src/platform/plugins/shared/console/common/types/autocomplete_definitions.ts

@@ -47,6 +47,13 @@ export interface EndpointDescription {
    */
   documentation?: string;
 
+  /**
+   * Serverless url of the documentation page of this endpoint.
+   * When `endpointsAvailability` is `serverless`, Console may use this value
+   * (if present) instead of the generic API reference link.
+   */
+  documentation_serverless?: string;
+
   /**
    * If the endpoint is available different environments (stack, serverless).
    */

src/platform/plugins/shared/console/packaging/scripts/console_definitions/generate_aggregated_definitions.ts

@@ -29,6 +29,7 @@ type UrlParamsDef = Record<string, UrlParamsValue>;
 interface EndpointDescription {
   availability?: EndpointAvailability;
   documentation?: string;
+  documentation_serverless?: string;
   id?: string;
   methods?: string[];
   patterns?: string[];
@@ -91,7 +92,7 @@ class StandaloneSpecDefinitionsService {
   addEndpointDescription(
     endpoint: string,
     description: EndpointDescription = {},
-    docsLinkToApiReference = false
+    isServerless = false
   ) {
     let copiedDescription: EndpointDescription = {};
     if (this.endpoints[endpoint]) {
@@ -118,8 +119,9 @@ class StandaloneSpecDefinitionsService {
       Object.assign(description.url_params, urlParamsDef);
     }
 
-    if (docsLinkToApiReference) {
-      description.documentation = 'https://www.elastic.co/docs/api';
+    if (isServerless) {
+      description.documentation =
+        description.documentation_serverless || 'https://www.elastic.co/docs/api';
     }
 
     Object.assign(copiedDescription, description);

src/platform/plugins/shared/console/server/services/spec_definitions_service.test.ts

@@ -29,18 +29,24 @@ const getMockEndpoint = ({
   methods,
   patterns,
   data_autocomplete_rules,
+  documentation,
+  documentation_serverless,
   availability,
 }: {
   endpointName: string;
   methods?: string[];
   patterns?: string[];
   data_autocomplete_rules?: Record<string, unknown>;
+  documentation?: string;
+  documentation_serverless?: string;
   availability?: Record<EndpointsAvailability, boolean>;
 }): EndpointDefinition => ({
   [endpointName]: {
     methods: methods ?? ['GET'],
     patterns: patterns ?? ['/endpoint'],
     data_autocomplete_rules: data_autocomplete_rules ?? undefined,
+    documentation: documentation ?? undefined,
+    documentation_serverless: documentation_serverless ?? undefined,
     availability: availability ?? undefined,
   },
 });
@@ -363,4 +369,52 @@ describe('SpecDefinitionsService', () => {
       },
     });
   });
+
+  it('uses documentation_serverless for serverless endpoints when present', () => {
+    mockGlobbySync.mockImplementation((pattern) => {
+      if (pattern.includes('generated')) {
+        return ['/generated/endpoint1.json', '/generated/endpoint2.json'];
+      }
+      return [];
+    });
+
+    mockReadFileSync.mockImplementation((path) => {
+      if (path.toString() === '/generated/endpoint1.json') {
+        return JSON.stringify(
+          getMockEndpoint({
+            endpointName: 'endpoint1',
+            availability: { stack: true, serverless: false },
+          })
+        );
+      }
+      if (path.toString() === '/generated/endpoint2.json') {
+        return JSON.stringify(
+          getMockEndpoint({
+            endpointName: 'endpoint2',
+            methods: ['POST'],
+            patterns: ['/endpoint2'],
+            documentation_serverless: 'https://docs.elastic.co/serverless/endpoint2',
+            availability: { stack: true, serverless: true },
+          })
+        );
+      }
+      return '';
+    });
+
+    const specDefinitionsService = new SpecDefinitionsService();
+    specDefinitionsService.start({
+      endpointsAvailability: 'serverless',
+    });
+    const endpoints = specDefinitionsService.asJson().endpoints;
+    expect(endpoints).toEqual({
+      endpoint2: {
+        availability: { stack: true, serverless: true },
+        id: 'endpoint2',
+        documentation: 'https://docs.elastic.co/serverless/endpoint2',
+        documentation_serverless: 'https://docs.elastic.co/serverless/endpoint2',
+        methods: ['POST'],
+        patterns: ['/endpoint2'],
+      },
+    });
+  });
 });

src/platform/plugins/shared/console/server/services/spec_definitions_service.ts

@@ -46,7 +46,7 @@ export class SpecDefinitionsService {
   public addEndpointDescription(
     endpoint: string,
     description: EndpointDescription = {},
-    docsLinkToApiReference: boolean = false
+    isServerless: boolean = false
   ) {
     let copiedDescription: EndpointDescription = {};
     if (this.endpoints[endpoint]) {
@@ -74,8 +74,8 @@ export class SpecDefinitionsService {
       _.defaults(description.url_params, urlParamsDef);
     }
 
-    if (docsLinkToApiReference) {
-      description.documentation = API_DOCS_LINK;
+    if (isServerless) {
+      description.documentation = description.documentation_serverless || API_DOCS_LINK;
     }
 
     _.assign(copiedDescription, description);