[8.15] [DOCS][OAS] Add descriptions, tags, deprecation to connector A…

…PIs (#184956) (#189237)

# Backport

This will backport the following commits from `main` to `8.15`:
- [[DOCS][OAS] Add descriptions, tags, deprecation to connector APIs
(#184956)](#184956)

<!--- Backport version: 8.9.8 -->

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

<!--BACKPORT [{"author":{"name":"Lisa
Cawley","email":"[email protected]"},"sourceCommit":{"committedDate":"2024-07-25T21:46:30Z","message":"[DOCS][OAS]
Add descriptions, tags, deprecation to connector APIs
(#184956)","sha":"e6795e5b0a58f8369e354fc2806531a173b052c9","branchLabelMapping":{"^v8.16.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","Team:ResponseOps","docs","backport:prev-minor","Feature:OAS","v8.16.0"],"number":184956,"url":"https://github.com/elastic/kibana/pull/184956","mergeCommit":{"message":"[DOCS][OAS]
Add descriptions, tags, deprecation to connector APIs
(#184956)","sha":"e6795e5b0a58f8369e354fc2806531a173b052c9"}},"sourceBranch":"main","suggestedTargetBranches":[],"targetPullRequestStates":[{"branch":"main","label":"v8.16.0","labelRegex":"^v8.16.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/184956","number":184956,"mergeCommit":{"message":"[DOCS][OAS]
Add descriptions, tags, deprecation to connector APIs
(#184956)","sha":"e6795e5b0a58f8369e354fc2806531a173b052c9"}}]}]
BACKPORT-->

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

@@ -8,5 +8,12 @@
 import { schema } from '@kbn/config-schema';
 
 export const connectorTypesQuerySchema = schema.object({
-  feature_id: schema.maybe(schema.string()),
+  feature_id: schema.maybe(
+    schema.string({
+      meta: {
+        description:
+          'A filter to limit the retrieved connector types to those that support a specific feature (such as alerting or cases).',
+      },
+    })
+  ),
 });

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

@@ -8,5 +8,7 @@
 import { schema } from '@kbn/config-schema';
 
 export const getConnectorParamsSchema = schema.object({
-  id: schema.string(),
+  id: schema.string({
+    meta: { description: 'An identifier for the connector.' },
+  }),
 });

x-pack/plugins/actions/docs/openapi/README.md

@@ -13,15 +13,7 @@ A guide about the openApi specification can be found at [https://swagger.io/docs
 
 ## Tools
 
-It is possible to validate the docs before bundling them with the following
-command in the `x-pack/plugins/actions/docs/openapi/` folder:
-
-```
-npx swagger-cli validate entrypoint.yaml
-npx swagger-cli validate entrypoint_serverless.yaml
-```
-
-Then you can generate the `bundled` files by running the following commands:
+You can generate the `bundled` files by running the following commands:
 
 ```
 npx @redocly/cli bundle entrypoint.yaml --output bundled.yaml --ext yaml
@@ -30,9 +22,4 @@ npx @redocly/cli bundle entrypoint_serverless.yaml --output bundled_serverless.y
 npx @redocly/cli bundle entrypoint_serverless.yaml --output bundled_serverless.json --ext json
 ```
 
-You can run additional linting with the following command:
-
-```
-npx @redocly/cli lint bundled.json
-npx @redocly/cli lint bundled_serverless.json
-```
+Then join these files with the rest of the Kibana APIs per `oas_docs/README.md`