[8.x] [ResponseOps] Connector OAS for framework fields (#192767) (#19…

…3349)

# Backport

This will backport the following commits from `main` to `8.x`:
- [[ResponseOps] Connector OAS for framework fields
(#192767)](#192767)

<!--- Backport version: 9.4.3 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT [{"author":{"name":"Alexi
Doak","email":"109488926+doakalexi@users.noreply.github.com"},"sourceCommit":{"committedDate":"2024-09-18T18:53:36Z","message":"[ResponseOps]
Connector OAS for framework fields (#192767)\n\nResolves
https://github.com/elastic/kibana/issues/192778\r\n\r\n##
Summary\r\n\r\nThis PR updates the following `response` schemas as well
as the legacy\r\nroute schemas for connector APIs to generate OAS
documentation:\r\n- `POST /api/actions/connector/{id?}`\r\n- `GET
/api/actions/connector/{id}`\r\n- `POST
/api/actions/connector/{id}/_execute`\r\n- `PUT
/api/actions/connector/{id}`\r\n\r\nThe `request` schemas were updated
in
this\r\n[PR](https://github.com/elastic/kibana/pull/191678).\r\n\r\n\r\n###
To verify\r\n\r\n1. Start ES\r\n2. Add `server.oas.enabled: true` to
`kibana.dev.yml`\r\n3. Start Kibana `yarn start --no-base-path`\r\n4.
`curl -s
-uelastic:changeme\r\nhttp://localhost:5601/api/oas\\?pathStartsWith\\=/api/actions/
| jq`\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine
<42973632+kibanamachine@users.noreply.github.com>\r\nCo-authored-by:
Lisa Cawley
<lcawley@elastic.co>","sha":"3c01b13f90d6c8b6c144e0c4ead771008d499d99","branchLabelMapping":{"^v9.0.0$":"main","^v8.16.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","Team:ResponseOps","v9.0.0","backport:prev-minor","v8.16.0"],"title":"[ResponseOps]
Connector OAS for framework
fields","number":192767,"url":"https://github.com/elastic/kibana/pull/192767","mergeCommit":{"message":"[ResponseOps]
Connector OAS for framework fields (#192767)\n\nResolves
https://github.com/elastic/kibana/issues/192778\r\n\r\n##
Summary\r\n\r\nThis PR updates the following `response` schemas as well
as the legacy\r\nroute schemas for connector APIs to generate OAS
documentation:\r\n- `POST /api/actions/connector/{id?}`\r\n- `GET
/api/actions/connector/{id}`\r\n- `POST
/api/actions/connector/{id}/_execute`\r\n- `PUT
/api/actions/connector/{id}`\r\n\r\nThe `request` schemas were updated
in
this\r\n[PR](https://github.com/elastic/kibana/pull/191678).\r\n\r\n\r\n###
To verify\r\n\r\n1. Start ES\r\n2. Add `server.oas.enabled: true` to
`kibana.dev.yml`\r\n3. Start Kibana `yarn start --no-base-path`\r\n4.
`curl -s
-uelastic:changeme\r\nhttp://localhost:5601/api/oas\\?pathStartsWith\\=/api/actions/
| jq`\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine
<42973632+kibanamachine@users.noreply.github.com>\r\nCo-authored-by:
Lisa Cawley
<lcawley@elastic.co>","sha":"3c01b13f90d6c8b6c144e0c4ead771008d499d99"}},"sourceBranch":"main","suggestedTargetBranches":["8.x"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","branchLabelMappingKey":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/192767","number":192767,"mergeCommit":{"message":"[ResponseOps]
Connector OAS for framework fields (#192767)\n\nResolves
https://github.com/elastic/kibana/issues/192778\r\n\r\n##
Summary\r\n\r\nThis PR updates the following `response` schemas as well
as the legacy\r\nroute schemas for connector APIs to generate OAS
documentation:\r\n- `POST /api/actions/connector/{id?}`\r\n- `GET
/api/actions/connector/{id}`\r\n- `POST
/api/actions/connector/{id}/_execute`\r\n- `PUT
/api/actions/connector/{id}`\r\n\r\nThe `request` schemas were updated
in
this\r\n[PR](https://github.com/elastic/kibana/pull/191678).\r\n\r\n\r\n###
To verify\r\n\r\n1. Start ES\r\n2. Add `server.oas.enabled: true` to
`kibana.dev.yml`\r\n3. Start Kibana `yarn start --no-base-path`\r\n4.
`curl -s
-uelastic:changeme\r\nhttp://localhost:5601/api/oas\\?pathStartsWith\\=/api/actions/
| jq`\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine
<42973632+kibanamachine@users.noreply.github.com>\r\nCo-authored-by:
Lisa Cawley
<lcawley@elastic.co>","sha":"3c01b13f90d6c8b6c144e0c4ead771008d499d99"}},{"branch":"8.x","label":"v8.16.0","branchLabelMappingKey":"^v8.16.0$","isSourceBranch":false,"state":"NOT_CREATED"}]}]
BACKPORT-->

Co-authored-by: Alexi Doak <109488926+doakalexi@users.noreply.github.com>

x-pack/plugins/actions/common/routes/connector/response/schemas/v1.ts

@@ -8,34 +8,93 @@
 import { schema } from '@kbn/config-schema';
 
 export const connectorResponseSchema = schema.object({
-  id: schema.string(),
-  name: schema.string(),
+  id: schema.string({
+    meta: {
+      description: 'The identifier for the connector.',
+    },
+  }),
+  name: schema.string({
+    meta: {
+      description: ' The name of the rule.',
+    },
+  }),
   config: schema.maybe(schema.recordOf(schema.string(), schema.any())),
-  connector_type_id: schema.string(),
-  is_missing_secrets: schema.maybe(schema.boolean()),
-  is_preconfigured: schema.boolean(),
-  is_deprecated: schema.boolean(),
-  is_system_action: schema.boolean(),
+  connector_type_id: schema.string({
+    meta: { description: 'The connector type identifier.' },
+  }),
+  is_missing_secrets: schema.maybe(
+    schema.boolean({ meta: { description: 'Indicates whether the connector is missing secrets.' } })
+  ),
+  is_preconfigured: schema.boolean({
+    meta: {
+      description:
+        'Indicates whether the connector is preconfigured. If true, the `config` and `is_missing_secrets` properties are omitted from the response. ',
+    },
+  }),
+  is_deprecated: schema.boolean({
+    meta: { description: 'Indicates whether the connector is deprecated.' },
+  }),
+  is_system_action: schema.boolean({
+    meta: { description: 'Indicates whether the connector is used for system actions.' },
+  }),
 });
 
 export const allConnectorsResponseSchema = connectorResponseSchema.extends({
-  referenced_by_count: schema.number(),
+  referenced_by_count: schema.number({
+    meta: {
+      description:
+        'The number of saved objects that reference the connector. If is_preconfigured is true, this value is not calculated.',
+    },
+  }),
 });
 
 export const connectorTypesResponseSchema = schema.object({
-  id: schema.string(),
-  name: schema.string(),
-  enabled: schema.boolean(),
-  enabled_in_config: schema.boolean(),
-  enabled_in_license: schema.boolean(),
-  minimum_license_required: schema.oneOf([
-    schema.literal('basic'),
-    schema.literal('standard'),
-    schema.literal('gold'),
-    schema.literal('platinum'),
-    schema.literal('enterprise'),
-    schema.literal('trial'),
-  ]),
-  supported_feature_ids: schema.arrayOf(schema.string()),
-  is_system_action_type: schema.boolean(),
+  id: schema.string({
+    meta: {
+      description: 'The identifier for the connector.',
+    },
+  }),
+  name: schema.string({
+    meta: {
+      description: ' The name of the rule.',
+    },
+  }),
+  enabled: schema.boolean({
+    meta: {
+      description: 'Indicates whether the connector is enabled.',
+    },
+  }),
+  enabled_in_config: schema.boolean({
+    meta: {
+      description: 'Indicates whether the connector is enabled in the Kibana configuration.',
+    },
+  }),
+  enabled_in_license: schema.boolean({
+    meta: {
+      description: 'Indicates whether the connector is enabled through the license.',
+    },
+  }),
+  minimum_license_required: schema.oneOf(
+    [
+      schema.literal('basic'),
+      schema.literal('standard'),
+      schema.literal('gold'),
+      schema.literal('platinum'),
+      schema.literal('enterprise'),
+      schema.literal('trial'),
+    ],
+    {
+      meta: {
+        description: 'The minimum license required to enable the connector.',
+      },
+    }
+  ),
+  supported_feature_ids: schema.arrayOf(schema.string(), {
+    meta: {
+      description: 'The minimum license required to enable the connector.',
+    },
+  }),
+  is_system_action_type: schema.boolean({
+    meta: { description: 'Indicates whether the action is a system action.' },
+  }),
 });

x-pack/plugins/actions/server/routes/connector/get/get.ts

@@ -10,6 +10,7 @@ import {
   getConnectorParamsSchemaV1,
   GetConnectorParamsV1,
 } from '../../../../common/routes/connector/apis/get';
+import { connectorResponseSchemaV1 } from '../../../../common/routes/connector/response';
 import { transformGetConnectorResponseV1 } from './transforms';
 import { ILicenseState } from '../../../lib';
 import { BASE_ACTION_API_PATH } from '../../../../common';
@@ -34,6 +35,7 @@ export const getConnectorRoute = (
         },
         response: {
           200: {
+            body: () => connectorResponseSchemaV1,
             description: 'Indicates a successful call.',
           },
         },

x-pack/plugins/actions/server/routes/create.ts

@@ -12,6 +12,7 @@ import { ILicenseState, validateEmptyStrings } from '../lib';
 import { BASE_ACTION_API_PATH, RewriteRequestCase, RewriteResponseCase } from '../../common';
 import { verifyAccessAndContext } from './verify_access_and_context';
 import { CreateOptions } from '../actions_client';
+import { connectorResponseSchemaV1 } from '../../common/routes/connector/response';
 
 export const bodySchema = schema.object({
   name: schema.string({
@@ -68,14 +69,17 @@ export const createActionRoute = (
         request: {
           params: schema.maybe(
             schema.object({
-              id: schema.maybe(schema.string()),
+              id: schema.maybe(
+                schema.string({ meta: { description: 'An identifier for the connector.' } })
+              ),
             })
           ),
           body: bodySchema,
         },
         response: {
           200: {
             description: 'Indicates a successful call.',
+            body: () => connectorResponseSchemaV1,
           },
         },
       },

x-pack/plugins/actions/server/routes/execute.ts

@@ -13,6 +13,7 @@ import { ActionTypeExecutorResult, ActionsRequestHandlerContext } from '../types
 import { BASE_ACTION_API_PATH, RewriteResponseCase } from '../../common';
 import { asHttpRequestExecutionSource } from '../lib/action_execution_source';
 import { verifyAccessAndContext } from './verify_access_and_context';
+import { connectorResponseSchemaV1 } from '../../common/routes/connector/response';
 
 const paramSchema = schema.object({
   id: schema.string({
@@ -56,6 +57,7 @@ export const executeActionRoute = (
         response: {
           200: {
             description: 'Indicates a successful call.',
+            body: () => connectorResponseSchemaV1,
           },
         },
       },

x-pack/plugins/actions/server/routes/legacy/create.ts

@@ -13,6 +13,7 @@ import { ILicenseState } from '../../lib';
 import { BASE_ACTION_API_PATH } from '../../../common';
 import { verifyAccessAndContext } from '../verify_access_and_context';
 import { trackLegacyRouteUsage } from '../../lib/track_legacy_route_usage';
+import { connectorResponseSchemaV1 } from '../../../common/routes/connector/response';
 
 export const bodySchema = schema.object({
   name: schema.string({
@@ -46,6 +47,7 @@ export const createActionRoute = (
         response: {
           200: {
             description: 'Indicates a successful call.',
+            body: () => connectorResponseSchemaV1,
           },
         },
       },

x-pack/plugins/actions/server/routes/legacy/execute.ts

@@ -14,6 +14,7 @@ import { ActionTypeExecutorResult, ActionsRequestHandlerContext } from '../../ty
 import { BASE_ACTION_API_PATH } from '../../../common';
 import { asHttpRequestExecutionSource } from '../../lib/action_execution_source';
 import { trackLegacyRouteUsage } from '../../lib/track_legacy_route_usage';
+import { connectorResponseSchemaV1 } from '../../../common/routes/connector/response';
 
 const paramSchema = schema.object({
   id: schema.string({
@@ -47,6 +48,7 @@ export const executeActionRoute = (
         response: {
           200: {
             description: 'Indicates a successful call.',
+            body: () => connectorResponseSchemaV1,
           },
         },
       },

x-pack/plugins/actions/server/routes/legacy/get.ts

@@ -12,6 +12,7 @@ import { ILicenseState, verifyApiAccess } from '../../lib';
 import { BASE_ACTION_API_PATH } from '../../../common';
 import { ActionsRequestHandlerContext } from '../../types';
 import { trackLegacyRouteUsage } from '../../lib/track_legacy_route_usage';
+import { connectorResponseSchemaV1 } from '../../../common/routes/connector/response';
 
 const paramSchema = schema.object({
   id: schema.string({
@@ -40,6 +41,7 @@ export const getActionRoute = (
         response: {
           200: {
             description: 'Indicates a successful call.',
+            body: () => connectorResponseSchemaV1,
           },
         },
       },

x-pack/plugins/actions/server/routes/legacy/update.ts

@@ -12,6 +12,7 @@ import { ILicenseState, verifyApiAccess, isErrorThatHandlesItsOwnResponse } from
 import { BASE_ACTION_API_PATH } from '../../../common';
 import { ActionsRequestHandlerContext } from '../../types';
 import { trackLegacyRouteUsage } from '../../lib/track_legacy_route_usage';
+import { connectorResponseSchemaV1 } from '../../../common/routes/connector/response';
 
 const paramSchema = schema.object({
   id: schema.string({
@@ -47,6 +48,7 @@ export const updateActionRoute = (
         response: {
           200: {
             description: 'Indicates a successful call.',
+            body: () => connectorResponseSchemaV1,
           },
         },
       },

x-pack/plugins/actions/server/routes/update.ts

@@ -11,6 +11,7 @@ import { ILicenseState, validateEmptyStrings } from '../lib';
 import { BASE_ACTION_API_PATH, RewriteResponseCase } from '../../common';
 import { ActionResult, ActionsRequestHandlerContext } from '../types';
 import { verifyAccessAndContext } from './verify_access_and_context';
+import { connectorResponseSchemaV1 } from '../../common/routes/connector/response';
 
 const paramSchema = schema.object({
   id: schema.string({
@@ -67,6 +68,7 @@ export const updateActionRoute = (
         response: {
           200: {
             description: 'Indicates a successful call.',
+            body: () => connectorResponseSchemaV1,
           },
         },
       },