[ResponseOps] Connector OAS for framework fields (#192767)

Resolves #192778

## Summary

This PR updates the following `response` schemas as well as the legacy
route schemas for connector APIs to generate OAS documentation:
- `POST /api/actions/connector/{id?}`
- `GET /api/actions/connector/{id}`
- `POST /api/actions/connector/{id}/_execute`
- `PUT /api/actions/connector/{id}`

The `request` schemas were updated in this
[PR](#191678).


### To verify

1. Start ES
2. Add `server.oas.enabled: true` to `kibana.dev.yml`
3. Start Kibana `yarn start --no-base-path`
4. `curl -s -uelastic:changeme
http://localhost:5601/api/oas\?pathStartsWith\=/api/actions/ | jq`

---------

Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
Co-authored-by: Lisa Cawley <lcawley@elastic.co>

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