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 cab011a5f0f72..c9d9c28a88823 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 @@ -43,7 +43,15 @@ describe('Router', () => { const router = new Router('', logger, enhanceWithContext, routerOptions); const validation = schema.object({ foo: schema.string() }); router.post( - { path: '/', validate: { body: validation, query: validation, params: validation } }, + { + path: '/', + validate: { body: validation, query: validation, params: validation }, + options: { + deprecated: true, + summary: 'post test summary', + description: 'post test description', + }, + }, (context, req, res) => res.ok() ); const routes = router.getRoutes(); @@ -55,6 +63,11 @@ describe('Router', () => { path: '/', validationSchemas: { body: validation, query: validation, params: validation }, isVersioned: false, + options: { + deprecated: true, + summary: 'post test summary', + description: 'post test description', + }, }); }); diff --git a/packages/core/http/core-http-router-server-internal/src/versioned_router/core_versioned_router.test.ts b/packages/core/http/core-http-router-server-internal/src/versioned_router/core_versioned_router.test.ts index 8b5a7d23fa0ee..c29a3edd967af 100644 --- a/packages/core/http/core-http-router-server-internal/src/versioned_router/core_versioned_router.test.ts +++ b/packages/core/http/core-http-router-server-internal/src/versioned_router/core_versioned_router.test.ts @@ -32,8 +32,13 @@ describe('Versioned router', () => { it('provides the expected metadata', () => { const versionedRouter = CoreVersionedRouter.from({ router }); - versionedRouter.get({ path: '/test/{id}', access: 'internal' }); - versionedRouter.post({ path: '/test', access: 'internal' }); + versionedRouter.get({ path: '/test/{id}', access: 'internal', deprecated: true }); + versionedRouter.post({ + path: '/test', + access: 'internal', + summary: 'Post test', + description: 'Post test description', + }); versionedRouter.delete({ path: '/test', access: 'internal' }); expect(versionedRouter.getRoutes()).toMatchInlineSnapshot(` Array [ @@ -42,6 +47,7 @@ describe('Versioned router', () => { "method": "get", "options": Object { "access": "internal", + "deprecated": true, }, "path": "/test/{id}", }, @@ -50,6 +56,8 @@ describe('Versioned router', () => { "method": "post", "options": Object { "access": "internal", + "description": "Post test description", + "summary": "Post test", }, "path": "/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 983c495a1b541..aa5b8598e0d0b 100644 --- a/packages/core/http/core-http-server/src/router/route.ts +++ b/packages/core/http/core-http-server/src/router/route.ts @@ -198,6 +198,14 @@ export interface RouteConfigOptions { * ``` */ description?: string; + + /** + * Setting this to `true` declares this route to be deprecated. Consumers SHOULD + * refrain from usage of this route. + * + * @remarks This will be surfaced in OAS documentation. + */ + deprecated?: boolean; } /** 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 af3173691415f..5c4eb459196cc 100644 --- a/packages/core/http/core-http-server/src/versioning/types.ts +++ b/packages/core/http/core-http-server/src/versioning/types.ts @@ -32,7 +32,7 @@ export type VersionedRouteConfig = Omit< RouteConfig, 'validate' | 'options' > & { - options?: Omit, 'access' | 'description'>; + options?: Omit, 'access' | 'description' | 'deprecated'>; /** See {@link RouteConfigOptions['access']} */ access: Exclude['access'], undefined>; /** @@ -82,6 +82,14 @@ export type VersionedRouteConfig = Omit< * ``` */ description?: string; + + /** + * Declares this operation to be deprecated. Consumers SHOULD refrain from usage + * of this route. This will be surfaced in OAS documentation. + * + * @default false + */ + deprecated?: boolean; }; /** diff --git a/packages/kbn-router-to-openapispec/src/__snapshots__/generate_oas.test.ts.snap b/packages/kbn-router-to-openapispec/src/__snapshots__/generate_oas.test.ts.snap index fee1a8534a7ec..be1b698f5cd9a 100644 --- a/packages/kbn-router-to-openapispec/src/__snapshots__/generate_oas.test.ts.snap +++ b/packages/kbn-router-to-openapispec/src/__snapshots__/generate_oas.test.ts.snap @@ -26,7 +26,6 @@ Object { "paths": Object { "/foo/{id}": Object { "get": Object { - "description": undefined, "operationId": "/foo/{id}#0", "parameters": Array [ Object { @@ -133,7 +132,7 @@ Object { "paths": Object { "/bar": Object { "get": Object { - "description": undefined, + "deprecated": true, "operationId": "/bar#0", "parameters": Array [ Object { @@ -577,7 +576,6 @@ Object { "paths": Object { "/recursive": Object { "get": Object { - "description": undefined, "operationId": "/recursive#0", "parameters": Array [ Object { @@ -660,7 +658,6 @@ Object { "paths": Object { "/foo/{id}": Object { "get": Object { - "description": undefined, "operationId": "/foo/{id}#0", "parameters": Array [ Object { @@ -698,7 +695,6 @@ Object { }, "/test": Object { "get": Object { - "description": undefined, "operationId": "/test#0", "parameters": Array [ Object { diff --git a/packages/kbn-router-to-openapispec/src/generate_oas.test.util.ts b/packages/kbn-router-to-openapispec/src/generate_oas.test.util.ts index bed7d10c51d8e..2fb821018dcee 100644 --- a/packages/kbn-router-to-openapispec/src/generate_oas.test.util.ts +++ b/packages/kbn-router-to-openapispec/src/generate_oas.test.util.ts @@ -85,6 +85,7 @@ export const getVersionedRouterDefaults = () => ({ options: { summary: 'versioned route', access: 'public', + deprecated: true, options: { tags: ['ignore-me', 'oas-tag:versioned'], }, diff --git a/packages/kbn-router-to-openapispec/src/process_router.ts b/packages/kbn-router-to-openapispec/src/process_router.ts index 393b745b6aab3..9437612211a92 100644 --- a/packages/kbn-router-to-openapispec/src/process_router.ts +++ b/packages/kbn-router-to-openapispec/src/process_router.ts @@ -61,8 +61,9 @@ export const processRouter = ( const operation: OpenAPIV3.OperationObject = { summary: route.options.summary ?? '', - description: route.options.description, tags: route.options.tags ? extractTags(route.options.tags) : [], + ...(route.options.description ? { description: route.options.description } : {}), + ...(route.options.deprecated ? { deprecated: route.options.deprecated } : {}), requestBody: !!validationSchemas?.body ? { content: { 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 cc873b26835cf..19b41f4812a30 100644 --- a/packages/kbn-router-to-openapispec/src/process_versioned_router.ts +++ b/packages/kbn-router-to-openapispec/src/process_versioned_router.ts @@ -85,8 +85,9 @@ export const processVersionedRouter = ( const hasVersionFilter = Boolean(filters?.version); const operation: OpenAPIV3.OperationObject = { summary: route.options.summary ?? '', - description: route.options.description, tags: route.options.options?.tags ? extractTags(route.options.options.tags) : [], + ...(route.options.description ? { description: route.options.description } : {}), + ...(route.options.deprecated ? { deprecated: route.options.deprecated } : {}), requestBody: hasBody ? { content: hasVersionFilter