From 64b45e08841790343f8e9e3a04eac9cf7b1e99ef Mon Sep 17 00:00:00 2001 From: Antonio Date: Fri, 26 Jul 2024 08:10:15 +0200 Subject: [PATCH] [ResponseOps][Rules] OAS schema registration for newly versioned Rule APIs (#189153) ## Summary Issue: https://github.com/elastic/kibana/issues/187574 This PR updates `request` and `response` schemas below for rule APIs to generate OAS documentation: - `POST /api/alerting/rule/{id?}/_enable` - `POST /api/alerting/rule/{id?}/_disable` - `POST /api/alerting/rule/{id?}/_update_api_key` ### How to test 1. Start ES 2. Add `server.oas.enabled: true` to `kibana.dev.yml` 3. Start Kibana `yarn start --no-base-path` 4. `curl -s -u elastic:changeme http://localhost:5601/api/oas\?pathStartsWith\=/api/alerting/rule/ | jq` 5. Look for `_enable`, `_disable` and `_update_api_key` in the resulting JSON --- .../common/routes/rule/apis/disable/schemas/v1.ts | 15 +++++++++++++-- .../common/routes/rule/apis/enable/schemas/v1.ts | 6 +++++- .../routes/rule/apis/update_api_key/schemas/v1.ts | 6 +++++- x-pack/plugins/alerting/server/routes/index.ts | 2 +- .../rule/apis/disable/disable_rule_route.ts | 11 +++++++++-- ...ble_rule.test.ts => enable_rule_route.test.ts} | 2 +- .../{enable_rule.ts => enable_rule_route.ts} | 9 ++++++++- .../update_api_key/update_rule_api_key_route.ts | 9 ++++++++- 8 files changed, 50 insertions(+), 10 deletions(-) rename x-pack/plugins/alerting/server/routes/rule/apis/enable/{enable_rule.test.ts => enable_rule_route.test.ts} (97%) rename x-pack/plugins/alerting/server/routes/rule/apis/enable/{enable_rule.ts => enable_rule_route.ts} (88%) diff --git a/x-pack/plugins/alerting/common/routes/rule/apis/disable/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/apis/disable/schemas/v1.ts index 478f65e5a8fd6..3a6fee8366e16 100644 --- a/x-pack/plugins/alerting/common/routes/rule/apis/disable/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/rule/apis/disable/schemas/v1.ts @@ -10,11 +10,22 @@ import { schema } from '@kbn/config-schema'; export const disableRuleRequestBodySchema = schema.nullable( schema.maybe( schema.object({ - untrack: schema.maybe(schema.boolean({ defaultValue: false })), + untrack: schema.maybe( + schema.boolean({ + defaultValue: false, + meta: { + description: "Defines whether this rule's alerts should be untracked.", + }, + }) + ), }) ) ); export const disableRuleRequestParamsSchema = schema.object({ - id: schema.string(), + id: schema.string({ + meta: { + description: 'The identifier for the rule.', + }, + }), }); diff --git a/x-pack/plugins/alerting/common/routes/rule/apis/enable/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/apis/enable/schemas/v1.ts index cb4495e42d847..a67bdd75a5e71 100644 --- a/x-pack/plugins/alerting/common/routes/rule/apis/enable/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/rule/apis/enable/schemas/v1.ts @@ -8,5 +8,9 @@ import { schema } from '@kbn/config-schema'; export const enableRuleRequestParamsSchema = schema.object({ - id: schema.string(), + id: schema.string({ + meta: { + description: 'The identifier for the rule.', + }, + }), }); diff --git a/x-pack/plugins/alerting/common/routes/rule/apis/update_api_key/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/apis/update_api_key/schemas/v1.ts index 3cd4ab1ad6054..8e10ec6330491 100644 --- a/x-pack/plugins/alerting/common/routes/rule/apis/update_api_key/schemas/v1.ts +++ b/x-pack/plugins/alerting/common/routes/rule/apis/update_api_key/schemas/v1.ts @@ -8,5 +8,9 @@ import { schema } from '@kbn/config-schema'; export const updateApiKeyParamsSchema = schema.object({ - id: schema.string(), + id: schema.string({ + meta: { + description: 'The identifier for the rule.', + }, + }), }); diff --git a/x-pack/plugins/alerting/server/routes/index.ts b/x-pack/plugins/alerting/server/routes/index.ts index 5a43c83369488..648d661d1d612 100644 --- a/x-pack/plugins/alerting/server/routes/index.ts +++ b/x-pack/plugins/alerting/server/routes/index.ts @@ -19,7 +19,7 @@ import { updateRuleRoute } from './rule/apis/update/update_rule_route'; import { deleteRuleRoute } from './rule/apis/delete/delete_rule_route'; import { aggregateRulesRoute } from './rule/apis/aggregate/aggregate_rules_route'; import { disableRuleRoute } from './rule/apis/disable/disable_rule_route'; -import { enableRuleRoute } from './rule/apis/enable/enable_rule'; +import { enableRuleRoute } from './rule/apis/enable/enable_rule_route'; import { findRulesRoute, findInternalRulesRoute } from './rule/apis/find/find_rules_route'; import { getRuleAlertSummaryRoute } from './get_rule_alert_summary'; import { getRuleExecutionLogRoute } from './get_rule_execution_log'; diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/disable/disable_rule_route.ts b/x-pack/plugins/alerting/server/routes/rule/apis/disable/disable_rule_route.ts index 88f124ae48b19..df7f673fd1bc1 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/disable/disable_rule_route.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/disable/disable_rule_route.ts @@ -28,8 +28,15 @@ export const disableRuleRoute = ( summary: 'Disable a rule', }, validate: { - params: disableRuleRequestParamsSchemaV1, - body: disableRuleRequestBodySchemaV1, + request: { + params: disableRuleRequestParamsSchemaV1, + body: disableRuleRequestBodySchemaV1, + }, + response: { + 204: { + description: 'Indicates a successful call.', + }, + }, }, }, router.handleLegacyErrors( diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/enable/enable_rule.test.ts b/x-pack/plugins/alerting/server/routes/rule/apis/enable/enable_rule_route.test.ts similarity index 97% rename from x-pack/plugins/alerting/server/routes/rule/apis/enable/enable_rule.test.ts rename to x-pack/plugins/alerting/server/routes/rule/apis/enable/enable_rule_route.test.ts index 2a5108543b2fa..143fa082db606 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/enable/enable_rule.test.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/enable/enable_rule_route.test.ts @@ -5,7 +5,7 @@ * 2.0. */ -import { enableRuleRoute } from './enable_rule'; +import { enableRuleRoute } from './enable_rule_route'; import { httpServiceMock } from '@kbn/core/server/mocks'; import { licenseStateMock } from '../../../../lib/license_state.mock'; import { mockHandlerArguments } from '../../../_mock_handler_arguments'; diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/enable/enable_rule.ts b/x-pack/plugins/alerting/server/routes/rule/apis/enable/enable_rule_route.ts similarity index 88% rename from x-pack/plugins/alerting/server/routes/rule/apis/enable/enable_rule.ts rename to x-pack/plugins/alerting/server/routes/rule/apis/enable/enable_rule_route.ts index 1014fad0d74ca..55acc33487676 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/enable/enable_rule.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/enable/enable_rule_route.ts @@ -27,7 +27,14 @@ export const enableRuleRoute = ( summary: 'Enable a rule', }, validate: { - params: enableRuleRequestParamsSchemaV1, + request: { + params: enableRuleRequestParamsSchemaV1, + }, + response: { + 204: { + description: 'Indicates a successful call.', + }, + }, }, }, router.handleLegacyErrors( diff --git a/x-pack/plugins/alerting/server/routes/rule/apis/update_api_key/update_rule_api_key_route.ts b/x-pack/plugins/alerting/server/routes/rule/apis/update_api_key/update_rule_api_key_route.ts index aee5e9801f635..6646d0635d132 100644 --- a/x-pack/plugins/alerting/server/routes/rule/apis/update_api_key/update_rule_api_key_route.ts +++ b/x-pack/plugins/alerting/server/routes/rule/apis/update_api_key/update_rule_api_key_route.ts @@ -26,7 +26,14 @@ export const updateRuleApiKeyRoute = ( summary: 'Update the API key for a rule', }, validate: { - params: updateApiKeyParamsSchemaV1, + request: { + params: updateApiKeyParamsSchemaV1, + }, + response: { + 204: { + description: 'Indicates a successful call.', + }, + }, }, }, router.handleLegacyErrors(