[Response Ops][Cases] Use deprecation object (#201004)

## Summary

Adds deprecation object in deprecated cases routes

Closes [#196557](https://github.com/elastic/kibana/issues/196557)

---------

Co-authored-by: Lisa Cawley <lcawley@elastic.co>

docs/upgrade-notes.asciidoc

@@ -50,6 +50,27 @@ For Elastic Security solution release information, refer to {security-guide}/rel
 
 
 [discrete]
+[[breaking-201004]]
+.[Cases] Legacy deprecations (9.0.0)
+[%collapsible]
+====
+*Details* +
+`GET /api/cases/status` has been deprecated with no replacement. Deleted in v9.0.0
+
+`GET /api/cases/{case_id}/comments` has been replaced by `GET /api/cases/{case_id}/comments/_find` released in v7.13
+
+`GET /api/cases/<case_id>/user_actions` has been replaced by `GET /api/cases/<case_id>/user_actions/_find` released in v8.7
+
+`includeComments` parameter in `GET /api/cases/{case_id}` has been deprecated. Use `GET /api/cases/{case_id}/comments/_find` instead, released in v7.13
+
+*Impact* +
+Deprecated endpoints will fail with a 404 status code starting from version 9.0.0
+
+*Action* +
+Remove references to `GET /api/cases/status` endpoint.
+Replace references to deprecated endpoints with the replacements listed in the breaking change details.
+====
+
 [[breaking-199656]]
 .Removed all security v1 endpoints (9.0.0)
 [%collapsible]
@@ -112,4 +133,3 @@ To access the assistant, go to **Stack Management** > **Upgrade Assistant**.
 
 
 
-

packages/kbn-doc-links/src/get_doc_links.ts

@@ -1004,5 +1004,8 @@ export const getDocLinks = ({ kibanaBranch, buildFlavor }: GetDocLinkOptions): D
     inferenceManagement: {
       inferenceAPIDocumentation: `${ELASTIC_WEBSITE_URL}docs/api/doc/elasticsearch/operation/operation-inference-put`,
     },
+    cases: {
+      legacyApiDeprecations: `${KIBANA_DOCS}breaking-changes-summary.html#breaking-201004`,
+    },
   });
 };

packages/kbn-doc-links/src/types.ts

@@ -679,6 +679,9 @@ export interface DocLinks {
   readonly inferenceManagement: {
     readonly inferenceAPIDocumentation: string;
   };
+  readonly cases: {
+    readonly legacyApiDeprecations: string;
+  };
 }
 
 export type BuildFlavor = 'serverless' | 'traditional';

x-pack/plugins/cases/server/plugin.ts

@@ -131,7 +131,7 @@ export class CasePlugin
     registerRoutes({
       router,
       routes: [
-        ...getExternalRoutes({ isServerless }),
+        ...getExternalRoutes({ isServerless, docLinks: core.docLinks }),
         ...getInternalRoutes(this.userProfileService),
       ],
       logger: this.logger,

x-pack/plugins/cases/server/routes/api/comments/get_all_comment.test.ts

@@ -6,17 +6,40 @@
  */
 
 import { getAllCommentsRoute } from './get_all_comment';
+import { docLinksServiceMock } from '@kbn/core/server/mocks';
 
 describe('getAllCommentsRoute', () => {
+  const docLinks = docLinksServiceMock.createSetupContract();
+
   it('marks the endpoint internal in serverless', async () => {
-    const router = getAllCommentsRoute({ isServerless: true });
+    const router = getAllCommentsRoute({ isServerless: true, docLinks });
 
     expect(router.routerOptions?.access).toBe('internal');
   });
 
   it('marks the endpoint public in non-serverless', async () => {
-    const router = getAllCommentsRoute({ isServerless: false });
+    const router = getAllCommentsRoute({ isServerless: false, docLinks });
 
     expect(router.routerOptions?.access).toBe('public');
   });
+
+  it('should be deprecated', () => {
+    const router = getAllCommentsRoute({ docLinks });
+    expect(router.routerOptions?.deprecated).toMatchInlineSnapshot(
+      {
+        documentationUrl: expect.stringMatching(/#breaking-201004$/),
+      },
+      `
+      Object {
+        "documentationUrl": StringMatching /#breaking-201004\\$/,
+        "reason": Object {
+          "newApiMethod": "GET",
+          "newApiPath": "/api/cases/{case_id}/comments/_find",
+          "type": "migrate",
+        },
+        "severity": "warning",
+      }
+    `
+    );
+  });
 });

x-pack/plugins/cases/server/routes/api/comments/get_all_comment.ts

@@ -7,6 +7,7 @@
 
 import { schema } from '@kbn/config-schema';
 
+import type { DocLinksServiceSetup } from '@kbn/core/server';
 import { CASE_COMMENTS_URL } from '../../../../common/constants';
 import { createCaseError } from '../../../common/error';
 import { createCasesRoute } from '../create_cases_route';
@@ -15,7 +16,13 @@ import type { attachmentDomainV1 } from '../../../../common/types/domain';
 /**
  * @deprecated since version 8.1.0
  */
-export const getAllCommentsRoute = ({ isServerless }: { isServerless?: boolean }) =>
+export const getAllCommentsRoute = ({
+  isServerless,
+  docLinks,
+}: {
+  isServerless?: boolean;
+  docLinks: DocLinksServiceSetup;
+}) =>
   createCasesRoute({
     method: 'get',
     path: CASE_COMMENTS_URL,
@@ -32,8 +39,15 @@ export const getAllCommentsRoute = ({ isServerless }: { isServerless?: boolean }
       summary: `Gets all case comments`,
       tags: ['oas-tag:cases'],
       // description: 'You must have `read` privileges for the **Cases** feature in the **Management**, **Observability**, or **Security** section of the Kibana feature privileges, depending on the owner of the cases with the comments you\'re seeking.',
-      // @ts-expect-error TODO(https://github.com/elastic/kibana/issues/196095): Replace {RouteDeprecationInfo}
-      deprecated: true,
+      deprecated: {
+        documentationUrl: docLinks.links.cases.legacyApiDeprecations,
+        severity: 'warning',
+        reason: {
+          type: 'migrate',
+          newApiMethod: 'GET',
+          newApiPath: '/api/cases/{case_id}/comments/_find',
+        },
+      },
     },
     handler: async ({ context, request, response }) => {
       try {

x-pack/plugins/cases/server/routes/api/get_external_routes.ts

@@ -5,6 +5,7 @@
  * 2.0.
  */
 
+import type { DocLinksServiceSetup } from '@kbn/core/server';
 import { getCasesByAlertIdRoute } from './cases/alerts/get_cases';
 import { deleteCaseRoute } from './cases/delete_cases';
 import { findCaseRoute } from './cases/find_cases';
@@ -32,7 +33,13 @@ import { getAllAlertsAttachedToCaseRoute } from './comments/get_alerts';
 import { findUserActionsRoute } from './user_actions/find_user_actions';
 import { postFileRoute } from './files/post_file';
 
-export const getExternalRoutes = ({ isServerless }: { isServerless?: boolean }) =>
+export const getExternalRoutes = ({
+  isServerless,
+  docLinks,
+}: {
+  isServerless?: boolean;
+  docLinks: DocLinksServiceSetup;
+}) =>
   [
     deleteCaseRoute,
     findCaseRoute,
@@ -42,8 +49,8 @@ export const getExternalRoutes = ({ isServerless }: { isServerless?: boolean })
     postCaseRoute,
     pushCaseRoute,
     findUserActionsRoute,
-    getUserActionsRoute({ isServerless }),
-    getStatusRoute({ isServerless }),
+    getUserActionsRoute({ isServerless, docLinks }),
+    getStatusRoute({ isServerless, docLinks }),
     getCasesByAlertIdRoute,
     getReportersRoute,
     getTagsRoute,
@@ -51,7 +58,7 @@ export const getExternalRoutes = ({ isServerless }: { isServerless?: boolean })
     deleteAllCommentsRoute,
     findCommentsRoute,
     getCommentRoute,
-    getAllCommentsRoute({ isServerless }),
+    getAllCommentsRoute({ isServerless, docLinks }),
     patchCommentRoute,
     postCommentRoute,
     getCaseConfigureRoute,

x-pack/plugins/cases/server/routes/api/stats/get_status.test.ts

@@ -6,16 +6,33 @@
  */
 
 import { getStatusRoute } from './get_status';
+import { docLinksServiceMock } from '@kbn/core/server/mocks';
 
 describe('getStatusRoute', () => {
+  const docLinks = docLinksServiceMock.createSetupContract();
+
   it('marks the endpoint internal in serverless', async () => {
-    const router = getStatusRoute({ isServerless: true });
+    const router = getStatusRoute({ isServerless: true, docLinks });
 
     expect(router.routerOptions?.access).toBe('internal');
+    expect(router.routerOptions?.deprecated).toMatchInlineSnapshot(
+      {
+        documentationUrl: expect.stringMatching(/#breaking-201004$/),
+      },
+      `
+      Object {
+        "documentationUrl": StringMatching /#breaking-201004\\$/,
+        "reason": Object {
+          "type": "remove",
+        },
+        "severity": "warning",
+      }
+    `
+    );
   });
 
   it('marks the endpoint public in non-serverless', async () => {
-    const router = getStatusRoute({ isServerless: false });
+    const router = getStatusRoute({ isServerless: false, docLinks });
 
     expect(router.routerOptions?.access).toBe('public');
   });

x-pack/plugins/cases/server/routes/api/stats/get_status.ts

@@ -5,6 +5,7 @@
  * 2.0.
  */
 
+import type { DocLinksServiceSetup } from '@kbn/core/server';
 import type { CaseRoute } from '../types';
 
 import { CASE_STATUS_URL } from '../../../../common/constants';
@@ -15,7 +16,13 @@ import type { statsApiV1 } from '../../../../common/types/api';
 /**
  * @deprecated since version 8.1.0
  */
-export const getStatusRoute = ({ isServerless }: { isServerless?: boolean }): CaseRoute =>
+export const getStatusRoute = ({
+  isServerless,
+  docLinks,
+}: {
+  isServerless?: boolean;
+  docLinks: DocLinksServiceSetup;
+}): CaseRoute =>
   createCasesRoute({
     method: 'get',
     path: CASE_STATUS_URL,
@@ -27,8 +34,13 @@ export const getStatusRoute = ({ isServerless }: { isServerless?: boolean }): Ca
       description:
         'Returns the number of cases that are open, closed, and in progress in the default space.',
       // You must have `read` privileges for the **Cases** feature in the **Management**, **Observability**, or **Security** section of the Kibana feature privileges, depending on the owner of the cases you're seeking.
-      // @ts-expect-error TODO(https://github.com/elastic/kibana/issues/196095): Replace {RouteDeprecationInfo}
-      deprecated: true,
+      deprecated: {
+        documentationUrl: docLinks.links.cases.legacyApiDeprecations,
+        severity: 'warning',
+        reason: {
+          type: 'remove',
+        },
+      },
     },
     handler: async ({ context, request, response }) => {
       try {

x-pack/plugins/cases/server/routes/api/user_actions/get_all_user_actions.test.ts

@@ -6,16 +6,35 @@
  */
 
 import { getUserActionsRoute } from './get_all_user_actions';
+import { docLinksServiceMock } from '@kbn/core/server/mocks';
 
 describe('getUserActionsRoute', () => {
+  const docLinks = docLinksServiceMock.createSetupContract();
+
   it('marks the endpoint internal in serverless', async () => {
-    const router = getUserActionsRoute({ isServerless: true });
+    const router = getUserActionsRoute({ isServerless: true, docLinks });
 
     expect(router.routerOptions?.access).toBe('internal');
+    expect(router.routerOptions?.deprecated).toMatchInlineSnapshot(
+      {
+        documentationUrl: expect.stringMatching(/#breaking-201004$/),
+      },
+      `
+      Object {
+        "documentationUrl": StringMatching /#breaking-201004\\$/,
+        "reason": Object {
+          "newApiMethod": "GET",
+          "newApiPath": "/api/cases/<case_id>/user_actions/_find",
+          "type": "migrate",
+        },
+        "severity": "warning",
+      }
+    `
+    );
   });
 
   it('marks the endpoint public in non-serverless', async () => {
-    const router = getUserActionsRoute({ isServerless: false });
+    const router = getUserActionsRoute({ isServerless: false, docLinks });
 
     expect(router.routerOptions?.access).toBe('public');
   });

x-pack/plugins/cases/server/routes/api/user_actions/get_all_user_actions.ts

@@ -7,6 +7,7 @@
 
 import { schema } from '@kbn/config-schema';
 
+import type { DocLinksServiceSetup } from '@kbn/core/server';
 import type { userActionApiV1 } from '../../../../common/types/api';
 import { CASE_USER_ACTIONS_URL } from '../../../../common/constants';
 import { createCaseError } from '../../../common/error';
@@ -15,7 +16,13 @@ import { createCasesRoute } from '../create_cases_route';
 /**
  * @deprecated since version 8.1.0
  */
-export const getUserActionsRoute = ({ isServerless }: { isServerless?: boolean }) =>
+export const getUserActionsRoute = ({
+  isServerless,
+  docLinks,
+}: {
+  isServerless?: boolean;
+  docLinks: DocLinksServiceSetup;
+}) =>
   createCasesRoute({
     method: 'get',
     path: CASE_USER_ACTIONS_URL,
@@ -31,8 +38,15 @@ export const getUserActionsRoute = ({ isServerless }: { isServerless?: boolean }
       description: `Returns all user activity for a case.`,
       // You must have `read` privileges for the **Cases** feature in the **Management**, **Observability**, or **Security** section of the Kibana feature privileges, depending on the owner of the case you're seeking.
       tags: ['oas-tag:cases'],
-      // @ts-expect-error TODO(https://github.com/elastic/kibana/issues/196095): Replace {RouteDeprecationInfo}
-      deprecated: true,
+      deprecated: {
+        documentationUrl: docLinks.links.cases.legacyApiDeprecations,
+        severity: 'warning',
+        reason: {
+          type: 'migrate',
+          newApiMethod: 'GET',
+          newApiPath: '/api/cases/<case_id>/user_actions/_find',
+        },
+      },
     },
     handler: async ({ context, request, response }) => {
       try {