Adds 'discontinued' to OAS meta

packages/core/http/core-http-router-server-internal/src/router.test.ts

@@ -49,6 +49,7 @@ describe('Router', () => {
           validate: { body: validation, query: validation, params: validation },
           options: {
             deprecated: true,
+            discontinued: 'post test discontinued',
             summary: 'post test summary',
             description: 'post test description',
           },
@@ -66,6 +67,7 @@ describe('Router', () => {
         isVersioned: false,
         options: {
           deprecated: true,
+          discontinued: 'post test discontinued',
           summary: 'post test summary',
           description: 'post test description',
         },

packages/core/http/core-http-router-server-internal/src/versioned_router/core_versioned_router.test.ts

@@ -33,7 +33,12 @@ describe('Versioned router', () => {
 
   it('provides the expected metadata', () => {
     const versionedRouter = CoreVersionedRouter.from({ router });
-    versionedRouter.get({ path: '/test/{id}', access: 'internal', deprecated: true });
+    versionedRouter.get({
+      path: '/test/{id}',
+      access: 'internal',
+      deprecated: true,
+      discontinued: 'x.y.z',
+    });
     versionedRouter.post({
       path: '/test',
       access: 'internal',
@@ -49,6 +54,7 @@ describe('Versioned router', () => {
           "options": Object {
             "access": "internal",
             "deprecated": true,
+            "discontinued": "x.y.z",
           },
           "path": "/test/{id}",
         },

packages/core/http/core-http-server/src/router/route.ts

@@ -207,6 +207,14 @@ export interface RouteConfigOptions<Method extends RouteMethod> {
    * @remarks This will be surfaced in OAS documentation.
    */
   deprecated?: boolean;
+
+  /**
+   * Release version or date that this route will be removed
+   * Use with `deprecated: true`
+   *
+   * @remarks This will be surfaced in OAS documentation.
+   */
+  discontinued?: string;
 }
 
 /**

packages/core/http/core-http-server/src/versioning/types.ts

@@ -91,6 +91,14 @@ export type VersionedRouteConfig<Method extends RouteMethod> = Omit<
    * @default false
    */
   deprecated?: boolean;
+
+  /**
+   * Release version or date that this route will be removed
+   * Use with `deprecated: true`
+   *
+   * @default undefined
+   */
+  discontinued?: string;
 };
 
 /**

packages/kbn-config-schema/index.ts

@@ -435,6 +435,7 @@ export const schema = {
 export type Schema = typeof schema;
 
 import {
+  META_FIELD_X_OAS_DISCONTINUED,
   META_FIELD_X_OAS_ANY,
   META_FIELD_X_OAS_OPTIONAL,
   META_FIELD_X_OAS_DEPRECATED,
@@ -444,6 +445,7 @@ import {
 } from './src/oas_meta_fields';
 
 export const metaFields = Object.freeze({
+  META_FIELD_X_OAS_DISCONTINUED,
   META_FIELD_X_OAS_ANY,
   META_FIELD_X_OAS_OPTIONAL,
   META_FIELD_X_OAS_DEPRECATED,

packages/kbn-config-schema/src/oas_meta_fields.ts

@@ -18,3 +18,4 @@ export const META_FIELD_X_OAS_GET_ADDITIONAL_PROPERTIES =
   'x-oas-get-additional-properties' as const;
 export const META_FIELD_X_OAS_DEPRECATED = 'x-oas-deprecated' as const;
 export const META_FIELD_X_OAS_ANY = 'x-oas-any-type' as const;
+export const META_FIELD_X_OAS_DISCONTINUED = 'x-oas-discontinued' as const;

packages/kbn-config-schema/src/types/type.test.ts

@@ -10,7 +10,7 @@
 import { get } from 'lodash';
 import { internals } from '../internals';
 import { Type, TypeOptions } from './type';
-import { META_FIELD_X_OAS_DEPRECATED } from '../oas_meta_fields';
+import { META_FIELD_X_OAS_DEPRECATED, META_FIELD_X_OAS_DISCONTINUED } from '../oas_meta_fields';
 
 class MyType extends Type<any> {
   constructor(opts: TypeOptions<any> = {}) {
@@ -26,6 +26,19 @@ describe('meta', () => {
     const meta = type.getSchema().describe();
     expect(get(meta, 'flags.description')).toBe('my description');
     expect(get(meta, `metas[0].${META_FIELD_X_OAS_DEPRECATED}`)).toBe(true);
+    expect(get(meta, `metas[1].${META_FIELD_X_OAS_DISCONTINUED}`)).toBeUndefined();
+  });
+
+  it('sets meta with all fields provided', () => {
+    const type = new MyType({
+      meta: { description: 'my description', deprecated: true, discontinued: '9.0.0' },
+    });
+    const meta = type.getSchema().describe();
+    expect(get(meta, 'flags.description')).toBe('my description');
+
+    expect(get(meta, `metas[0].${META_FIELD_X_OAS_DEPRECATED}`)).toBe(true);
+
+    expect(get(meta, `metas[1].${META_FIELD_X_OAS_DISCONTINUED}`)).toBe('9.0.0');
   });
 
   it('does not set meta when no provided', () => {

packages/kbn-config-schema/src/types/type.ts

@@ -16,7 +16,7 @@ import {
   type WhenOptions,
   CustomHelpers,
 } from 'joi';
-import { META_FIELD_X_OAS_DEPRECATED } from '../oas_meta_fields';
+import { META_FIELD_X_OAS_DEPRECATED, META_FIELD_X_OAS_DISCONTINUED } from '../oas_meta_fields';
 import { SchemaTypeError, ValidationError } from '../errors';
 import { Reference } from '../references';
 
@@ -33,6 +33,10 @@ export interface TypeMeta {
    * Whether this field is deprecated.
    */
   deprecated?: boolean;
+  /**
+   * Release version or date that this route will be removed
+   */
+  discontinued?: string;
 }
 
 export interface TypeOptions<T> {
@@ -129,6 +133,8 @@ export abstract class Type<V> {
       if (options.meta.deprecated) {
         schema = schema.meta({ [META_FIELD_X_OAS_DEPRECATED]: true });
       }
+      if (options.meta.deprecated && options.meta.discontinued)
+        schema = schema.meta({ [META_FIELD_X_OAS_DISCONTINUED]: options.meta.discontinued });
     }
 
     // Attach generic error handler only if it hasn't been attached yet since

packages/kbn-router-to-openapispec/src/generate_oas.test.fixture.ts

@@ -34,6 +34,7 @@ export const sharedOas = {
     '/bar': {
       get: {
         deprecated: true,
+        discontinued: 'route discontinued version or date',
         operationId: '%2Fbar#0',
         parameters: [
           {

packages/kbn-router-to-openapispec/src/generate_oas.test.util.ts

@@ -64,6 +64,7 @@ export const getVersionedRouterDefaults = (bodySchema?: RuntimeSchema) => ({
     summary: 'versioned route',
     access: 'public',
     deprecated: true,
+    discontinued: 'route discontinued version or date',
     options: {
       tags: ['ignore-me', 'oas-tag:versioned'],
     },
@@ -81,6 +82,15 @@ export const getVersionedRouterDefaults = (bodySchema?: RuntimeSchema) => ({
                 deprecatedFoo: schema.maybe(
                   schema.string({ meta: { description: 'deprecated foo', deprecated: true } })
                 ),
+                discontinuedFoo: schema.maybe(
+                  schema.string({
+                    meta: {
+                      description: 'discontinued foo',
+                      deprecated: true,
+                      discontinued: 'foo discontinued version or date',
+                    },
+                  })
+                ),
               }),
           },
           response: {

packages/kbn-router-to-openapispec/src/oas_converter/kbn_config_schema/post_process_mutations/mutations/index.ts

@@ -11,7 +11,7 @@ import Joi from 'joi';
 import { metaFields } from '@kbn/config-schema';
 import type { OpenAPIV3 } from 'openapi-types';
 import { parse } from '../../parse';
-import { deleteField, stripBadDefault, processDeprecated } from './utils';
+import { deleteField, stripBadDefault, processDeprecated, processDiscontinued } from './utils';
 import { IContext } from '../context';
 
 const {
@@ -58,13 +58,14 @@ export const processMap = (ctx: IContext, schema: OpenAPIV3.SchemaObject): void
 
 export const processAllTypes = (schema: OpenAPIV3.SchemaObject): void => {
   processDeprecated(schema);
+  processDiscontinued(schema);
   stripBadDefault(schema);
 };
 
 export const processAnyType = (schema: OpenAPIV3.SchemaObject): void => {
   // Map schema to an empty object: `{}`
   for (const key of Object.keys(schema)) {
-    deleteField(schema as Record<any, unknown>, key);
+    deleteField(schema as unknown as Record<any, unknown>, key);
   }
 };
 

packages/kbn-router-to-openapispec/src/oas_converter/kbn_config_schema/post_process_mutations/mutations/utils.ts

@@ -35,6 +35,13 @@ export const processDeprecated = (schema: OpenAPIV3.SchemaObject): void => {
   }
 };
 
+export const processDiscontinued = (schema: OpenAPIV3.SchemaObject): void => {
+  if (metaFields.META_FIELD_X_OAS_DISCONTINUED in schema) {
+    schema.discontinued = 'versionOrDate';
+    deleteField(schema, metaFields.META_FIELD_X_OAS_DISCONTINUED);
+  }
+};
+
 /** Just for type convenience */
 export const deleteField = (schema: Record<any, unknown>, field: string): void => {
   delete schema[field];

packages/kbn-router-to-openapispec/src/process_router.ts

@@ -66,6 +66,7 @@ export const processRouter = (
         tags: route.options.tags ? extractTags(route.options.tags) : [],
         ...(route.options.description ? { description: route.options.description } : {}),
         ...(route.options.deprecated ? { deprecated: route.options.deprecated } : {}),
+        ...(route.options.discontinued ? { discontinued: route.options.discontinued } : {}),
         requestBody: !!validationSchemas?.body
           ? {
               content: {

packages/kbn-router-to-openapispec/src/process_versioned_router.ts

@@ -98,6 +98,7 @@ export const processVersionedRouter = (
         tags: route.options.options?.tags ? extractTags(route.options.options.tags) : [],
         ...(route.options.description ? { description: route.options.description } : {}),
         ...(route.options.deprecated ? { deprecated: route.options.deprecated } : {}),
+        ...(route.options.discontinued ? { discontinued: route.options.discontinued } : {}),
         requestBody: hasBody
           ? {
               content: hasVersionFilter