diff --git a/packages/kbn-generate-console-definitions/src/generate_console_definitions.ts b/packages/kbn-generate-console-definitions/src/generate_console_definitions.ts index 9ba7f0ed57f71..e2a5a948566b8 100644 --- a/packages/kbn-generate-console-definitions/src/generate_console_definitions.ts +++ b/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; }; diff --git a/packages/kbn-generate-console-definitions/src/types/specification_types.ts b/packages/kbn-generate-console-definitions/src/types/specification_types.ts index fc2f694290801..f248a3d54ed4d 100644 --- a/packages/kbn-generate-console-definitions/src/types/specification_types.ts +++ b/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; diff --git a/src/platform/plugins/shared/console/common/types/autocomplete_definitions.ts b/src/platform/plugins/shared/console/common/types/autocomplete_definitions.ts index 7b16d480fd06d..875818cf4456a 100644 --- a/src/platform/plugins/shared/console/common/types/autocomplete_definitions.ts +++ b/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). */ diff --git a/src/platform/plugins/shared/console/packaging/scripts/console_definitions/generate_aggregated_definitions.ts b/src/platform/plugins/shared/console/packaging/scripts/console_definitions/generate_aggregated_definitions.ts index 633548c4c86a4..1cec831adde66 100644 --- a/src/platform/plugins/shared/console/packaging/scripts/console_definitions/generate_aggregated_definitions.ts +++ b/src/platform/plugins/shared/console/packaging/scripts/console_definitions/generate_aggregated_definitions.ts @@ -29,6 +29,7 @@ type UrlParamsDef = Record; 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); diff --git a/src/platform/plugins/shared/console/server/services/spec_definitions_service.test.ts b/src/platform/plugins/shared/console/server/services/spec_definitions_service.test.ts index 3a16bcca729c9..7bdfdd82d45e3 100644 --- a/src/platform/plugins/shared/console/server/services/spec_definitions_service.test.ts +++ b/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; + documentation?: string; + documentation_serverless?: string; availability?: Record; }): 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'], + }, + }); + }); }); diff --git a/src/platform/plugins/shared/console/server/services/spec_definitions_service.ts b/src/platform/plugins/shared/console/server/services/spec_definitions_service.ts index 936c689a2ca93..95ba16fb806b1 100644 --- a/src/platform/plugins/shared/console/server/services/spec_definitions_service.ts +++ b/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);