[OAS] Deprecations (#186062)

## Summary

Adds support for the [`deprecated`
field](https://swagger.io/specification/) at the operation level to our
router conversion logic.

Close #186003

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',
+        },
       });
     });
 

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",
         },

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

@@ -198,6 +198,14 @@ export interface RouteConfigOptions<Method extends RouteMethod> {
    * ```
    */
   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;
 }
 
 /**

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

@@ -32,7 +32,7 @@ export type VersionedRouteConfig<Method extends RouteMethod> = Omit<
   RouteConfig<unknown, unknown, unknown, Method>,
   'validate' | 'options'
 > & {
-  options?: Omit<RouteConfigOptions<Method>, 'access' | 'description'>;
+  options?: Omit<RouteConfigOptions<Method>, 'access' | 'description' | 'deprecated'>;
   /** See {@link RouteConfigOptions<RouteMethod>['access']} */
   access: Exclude<RouteConfigOptions<Method>['access'], undefined>;
   /**
@@ -82,6 +82,14 @@ export type VersionedRouteConfig<Method extends RouteMethod> = 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;
 };
 
 /**

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'],
     },

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: {

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