From 68c34c27f08cecba1771a1c76c6da78173153468 Mon Sep 17 00:00:00 2001 From: Jean-Louis Leysens Date: Mon, 21 Oct 2024 12:30:45 +0200 Subject: [PATCH] [OAS] Support setting availability (#196647) ## Summary Close https://github.com/elastic/kibana/issues/181995 Related https://github.com/elastic/kibana/pull/195325 ### Checklist - [x] [Unit or functional tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html) were updated or added to match the most common scenarios --------- Co-authored-by: Christiane (Tina) Heiligers (cherry picked from commit 608cc70be56fa63cb68a93d480e545fa95c0846a) --- .../src/router.test.ts | 8 ++ .../core_versioned_route.test.ts | 43 +++++++- .../http/core-http-server/src/router/route.ts | 17 ++++ .../core-http-server/src/versioning/types.ts | 2 +- .../openapi-types.d.ts | 2 +- .../src/generate_oas.test.ts | 99 +++++++++++++++++++ .../src/process_router.ts | 6 +- .../src/process_versioned_router.ts | 4 + .../kbn-router-to-openapispec/src/type.ts | 5 + .../kbn-router-to-openapispec/src/util.ts | 16 ++- 10 files changed, 197 insertions(+), 5 deletions(-) diff --git a/packages/core/http/core-http-router-server-internal/src/router.test.ts b/packages/core/http/core-http-router-server-internal/src/router.test.ts index c318e9312546a..f611e3b6308fe 100644 --- a/packages/core/http/core-http-router-server-internal/src/router.test.ts +++ b/packages/core/http/core-http-router-server-internal/src/router.test.ts @@ -54,6 +54,10 @@ describe('Router', () => { discontinued: 'post test discontinued', summary: 'post test summary', description: 'post test description', + availability: { + since: '1.0.0', + stability: 'experimental', + }, }, }, (context, req, res) => res.ok() @@ -72,6 +76,10 @@ describe('Router', () => { discontinued: 'post test discontinued', summary: 'post test summary', description: 'post test description', + availability: { + since: '1.0.0', + stability: 'experimental', + }, }, }); }); diff --git a/packages/core/http/core-http-router-server-internal/src/versioned_router/core_versioned_route.test.ts b/packages/core/http/core-http-router-server-internal/src/versioned_router/core_versioned_route.test.ts index 3938b8addfc25..1442467012d8b 100644 --- a/packages/core/http/core-http-router-server-internal/src/versioned_router/core_versioned_route.test.ts +++ b/packages/core/http/core-http-router-server-internal/src/versioned_router/core_versioned_route.test.ts @@ -52,6 +52,46 @@ describe('Versioned route', () => { jest.clearAllMocks(); }); + describe('#getRoutes', () => { + it('returns the expected metadata', () => { + const versionedRouter = CoreVersionedRouter.from({ router }); + versionedRouter + .get({ + path: '/test/{id}', + access: 'public', + options: { + httpResource: true, + availability: { + since: '1.0.0', + stability: 'experimental', + }, + excludeFromOAS: true, + tags: ['1', '2', '3'], + }, + description: 'test', + summary: 'test', + enableQueryVersion: false, + }) + .addVersion({ version: '2023-10-31', validate: false }, handlerFn); + + expect(versionedRouter.getRoutes()[0].options).toMatchObject({ + access: 'public', + enableQueryVersion: false, + description: 'test', + summary: 'test', + options: { + httpResource: true, + availability: { + since: '1.0.0', + stability: 'experimental', + }, + excludeFromOAS: true, + tags: ['1', '2', '3'], + }, + }); + }); + }); + it('can register multiple handlers', () => { const versionedRouter = CoreVersionedRouter.from({ router }); versionedRouter @@ -133,6 +173,8 @@ describe('Versioned route', () => { const opts: Parameters[0] = { path: '/test/{id}', access: 'internal', + summary: 'test', + description: 'test', options: { authRequired: true, tags: ['access:test'], @@ -140,7 +182,6 @@ describe('Versioned route', () => { xsrfRequired: false, excludeFromOAS: true, httpResource: true, - summary: `test`, }, }; diff --git a/packages/core/http/core-http-server/src/router/route.ts b/packages/core/http/core-http-server/src/router/route.ts index a97ff9dd4040b..ac723db924a5a 100644 --- a/packages/core/http/core-http-server/src/router/route.ts +++ b/packages/core/http/core-http-server/src/router/route.ts @@ -321,6 +321,23 @@ export interface RouteConfigOptions { * @default false */ httpResource?: boolean; + + /** + * Based on the the ES API specification (see https://github.com/elastic/elasticsearch-specification) + * Kibana APIs can also specify some metadata about API availability. + * + * This setting is only applicable if your route `access` is `public`. + * + * @remark intended to be used for informational purposes only. + */ + availability?: { + /** @default stable */ + stability?: 'experimental' | 'beta' | 'stable'; + /** + * The stack version in which the route was introduced (eg: 8.15.0). + */ + since?: string; + }; } /** diff --git a/packages/core/http/core-http-server/src/versioning/types.ts b/packages/core/http/core-http-server/src/versioning/types.ts index 60cbca014e683..7998c9cc91fa9 100644 --- a/packages/core/http/core-http-server/src/versioning/types.ts +++ b/packages/core/http/core-http-server/src/versioning/types.ts @@ -35,7 +35,7 @@ export type VersionedRouteConfig = Omit< > & { options?: Omit< RouteConfigOptions, - 'access' | 'description' | 'deprecated' | 'discontinued' | 'security' + 'access' | 'description' | 'summary' | 'deprecated' | 'discontinued' | 'security' >; /** See {@link RouteConfigOptions['access']} */ access: Exclude['access'], undefined>; diff --git a/packages/kbn-router-to-openapispec/openapi-types.d.ts b/packages/kbn-router-to-openapispec/openapi-types.d.ts index 90c034a855fdc..9689ed803a152 100644 --- a/packages/kbn-router-to-openapispec/openapi-types.d.ts +++ b/packages/kbn-router-to-openapispec/openapi-types.d.ts @@ -13,7 +13,7 @@ export * from 'openapi-types'; declare module 'openapi-types' { export namespace OpenAPIV3 { export interface BaseSchemaObject { - // Custom OpenAPI field added by Kibana for a new field at the shema level. + // Custom OpenAPI field added by Kibana for a new field at the schema level. 'x-discontinued'?: string; } } diff --git a/packages/kbn-router-to-openapispec/src/generate_oas.test.ts b/packages/kbn-router-to-openapispec/src/generate_oas.test.ts index 6db4237751217..c3532312d3088 100644 --- a/packages/kbn-router-to-openapispec/src/generate_oas.test.ts +++ b/packages/kbn-router-to-openapispec/src/generate_oas.test.ts @@ -321,4 +321,103 @@ describe('generateOpenApiDocument', () => { expect(result.paths['/v2-1']!.get!.tags).toEqual([]); }); }); + + describe('availability', () => { + it('creates the expected availability entries', () => { + const [routers, versionedRouters] = createTestRouters({ + routers: { + testRouter1: { + routes: [ + { + path: '/1-1/{id}/{path*}', + options: { availability: { stability: 'experimental' } }, + }, + { + path: '/1-2/{id}/{path*}', + options: { availability: { stability: 'beta' } }, + }, + { + path: '/1-3/{id}/{path*}', + options: { availability: { stability: 'stable' } }, + }, + ], + }, + testRouter2: { + routes: [{ path: '/2-1/{id}/{path*}' }], + }, + }, + versionedRouters: { + testVersionedRouter1: { + routes: [ + { + path: '/v1-1', + options: { + access: 'public', + options: { availability: { stability: 'experimental' } }, + }, + }, + { + path: '/v1-2', + options: { + access: 'public', + options: { availability: { stability: 'beta' } }, + }, + }, + { + path: '/v1-3', + options: { + access: 'public', + options: { availability: { stability: 'stable' } }, + }, + }, + ], + }, + testVersionedRouter2: { + routes: [{ path: '/v2-1', options: { access: 'public' } }], + }, + }, + }); + const result = generateOpenApiDocument( + { + routers, + versionedRouters, + }, + { + title: 'test', + baseUrl: 'https://test.oas', + version: '99.99.99', + } + ); + + // router paths + expect(result.paths['/1-1/{id}/{path*}']!.get).toMatchObject({ + 'x-state': 'Technical Preview', + }); + expect(result.paths['/1-2/{id}/{path*}']!.get).toMatchObject({ + 'x-state': 'Beta', + }); + + expect(result.paths['/1-3/{id}/{path*}']!.get).not.toMatchObject({ + 'x-state': expect.any(String), + }); + expect(result.paths['/2-1/{id}/{path*}']!.get).not.toMatchObject({ + 'x-state': expect.any(String), + }); + + // versioned router paths + expect(result.paths['/v1-1']!.get).toMatchObject({ + 'x-state': 'Technical Preview', + }); + expect(result.paths['/v1-2']!.get).toMatchObject({ + 'x-state': 'Beta', + }); + + expect(result.paths['/v1-3']!.get).not.toMatchObject({ + 'x-state': expect.any(String), + }); + expect(result.paths['/v2-1']!.get).not.toMatchObject({ + 'x-state': expect.any(String), + }); + }); + }); }); diff --git a/packages/kbn-router-to-openapispec/src/process_router.ts b/packages/kbn-router-to-openapispec/src/process_router.ts index 4437e35ea1f3e..1884b6dddf863 100644 --- a/packages/kbn-router-to-openapispec/src/process_router.ts +++ b/packages/kbn-router-to-openapispec/src/process_router.ts @@ -23,9 +23,11 @@ import { getVersionedHeaderParam, mergeResponseContent, prepareRoutes, + setXState, } from './util'; import type { OperationIdCounter } from './operation_id_counter'; import type { GenerateOpenApiDocumentOptionsFilters } from './generate_oas'; +import type { CustomOperationObject } from './type'; export const processRouter = ( appRouter: Router, @@ -61,7 +63,7 @@ export const processRouter = ( parameters.push(...pathObjects, ...queryObjects); } - const operation: OpenAPIV3.OperationObject = { + const operation: CustomOperationObject = { summary: route.options.summary ?? '', tags: route.options.tags ? extractTags(route.options.tags) : [], ...(route.options.description ? { description: route.options.description } : {}), @@ -81,6 +83,8 @@ export const processRouter = ( operationId: getOpId(route.path), }; + setXState(route.options.availability, operation); + const path: OpenAPIV3.PathItemObject = { [route.method]: operation, }; 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 97b92f92fde57..5446f1409760d 100644 --- a/packages/kbn-router-to-openapispec/src/process_versioned_router.ts +++ b/packages/kbn-router-to-openapispec/src/process_versioned_router.ts @@ -29,6 +29,7 @@ import { extractTags, mergeResponseContent, getXsrfHeaderForMethod, + setXState, } from './util'; export const processVersionedRouter = ( @@ -112,6 +113,9 @@ export const processVersionedRouter = ( parameters, operationId: getOpId(route.path), }; + + setXState(route.options.options?.availability, operation); + const path: OpenAPIV3.PathItemObject = { [route.method]: operation, }; diff --git a/packages/kbn-router-to-openapispec/src/type.ts b/packages/kbn-router-to-openapispec/src/type.ts index 09dc247e5a5c9..5c5f992a0de0f 100644 --- a/packages/kbn-router-to-openapispec/src/type.ts +++ b/packages/kbn-router-to-openapispec/src/type.ts @@ -34,3 +34,8 @@ export interface OpenAPIConverter { is(type: unknown): boolean; } + +export type CustomOperationObject = OpenAPIV3.OperationObject<{ + // Custom OpenAPI from ES API spec based on @availability + 'x-state'?: 'Technical Preview' | 'Beta'; +}>; diff --git a/packages/kbn-router-to-openapispec/src/util.ts b/packages/kbn-router-to-openapispec/src/util.ts index 55f7348dc199a..beefbebc0aec7 100644 --- a/packages/kbn-router-to-openapispec/src/util.ts +++ b/packages/kbn-router-to-openapispec/src/util.ts @@ -17,7 +17,7 @@ import { type RouterRoute, type RouteValidatorConfig, } from '@kbn/core-http-server'; -import { KnownParameters } from './type'; +import { CustomOperationObject, KnownParameters } from './type'; import type { GenerateOpenApiDocumentOptionsFilters } from './generate_oas'; const tagPrefix = 'oas-tag:'; @@ -165,3 +165,17 @@ export const getXsrfHeaderForMethod = ( }, ]; }; + +export function setXState( + availability: RouteConfigOptions['availability'], + operation: CustomOperationObject +): void { + if (availability) { + if (availability.stability === 'experimental') { + operation['x-state'] = 'Technical Preview'; + } + if (availability.stability === 'beta') { + operation['x-state'] = 'Beta'; + } + } +}