[ResponseOps][Rules] OAS schema registration for Rule APIs by js-jankisalvi · Pull Request #188445 · elastic/kibana

js-jankisalvi · 2024-07-16T14:34:11Z

Summary

Issue: #187574

This PR updates request and response schemas below for rule APIs to generate OAS documentation:

POST /api/alerting/rule/{id?}
GET /api/alerting/rule/{id}
DELETE /api/alerting/rule/{id}
PUT /api/alerting/rule/{id}
GET /api/alerting/rules/_find
POST /api/alerting/rule/{rule_id}/alert/{alert_id}/_mute

How to test

Start ES
Add server.oas.enabled: true to kibana.dev.yml
Start Kibana yarn start --no-base-path
curl -s -uelastic:changeme http://localhost:5601/api/oas\?pathStartsWith\=/api/alerting/rule/ | jq
For find api run curl -s -uelastic:changeme http://localhost:5601/api/oas\?pathStartsWith\=/api/alerting/rules/ | jq

elasticmachine · 2024-07-16T14:34:14Z

Pinging @elastic/response-ops (Team:ResponseOps)

js-jankisalvi · 2024-07-16T15:29:31Z

x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts

+          }),
+          { meta: { description: 'History of the rule run.' } }
+        ),
+        calculated_metrics: schema.object({


Couldn't find any docs, comments or example which could help explain this metrics. Would be great if someone can suggest description for calculated_metrics object.

How about "Calculation of different percentiles and success ratio"?

cnasikas

Tested and it is working as expected!

x-pack/plugins/alerting/server/routes/rule/apis/create/create_rule_route.ts

elasticmachine · 2024-07-18T15:21:38Z

💚 Build Succeeded

Buildkite Build
Commit: 800b759

Metrics [docs]

✅ unchanged

History

💛 Build #221805 was flaky b846f9b
💔 Build #221788 failed f2e7fa5

cc @js-jankisalvi

adcoelho

Tested and works 👌

JiaweiWu

code LGTM! I will approve when @lcawl looks over the descriptions and gives it a green light 😄

JiaweiWu · 2024-07-22T19:55:54Z

x-pack/plugins/alerting/server/routes/rule/apis/mute_alert/mute_alert.ts

      validate: {
-        params: muteAlertParamsSchemaV1,
+        request: {
+          params: muteAlertParamsSchemaV1,


Should we specify the 403 here? Since we have the RuleTypeDisabledError in 42, which sends out a custom error body. If so we should version that schema well

@lcawl what do you think?

@cnasikas has created an issue to handle 4xx and 5xx errors for all routes.
Is it fine if I handle error response and its schema versioning in a separate PR?

Yes, that seems fine to me!

JiaweiWu · 2024-07-22T19:56:21Z

x-pack/plugins/alerting/server/routes/rule/apis/update/update_rule_route.ts

+        },
+        response: {
+          200: {
+            body: () => ruleResponseSchemaV1,


Same here this can also 403

js-jankisalvi · 2024-07-23T09:13:12Z

Updated all response with description here as per this PR.

lcawl

Awesome! Added some feedback on the strings but otherwise LGTM!

x-pack/plugins/alerting/common/routes/alerts_filter_query/schemas/v1.ts

x-pack/plugins/alerting/common/routes/r_rule/response/schemas/v1.ts

x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts

x-pack/plugins/alerting/server/routes/rule/apis/find/find_rules_route.ts

kibana-ci · 2024-07-23T18:22:00Z

💛 Build succeeded, but was flaky

Buildkite Build
Commit: b05aff0

Failed CI Steps

Metrics [docs]

✅ unchanged

History

💚 Build #223144 succeeded 6cf0ed7

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

cc @js-jankisalvi

JiaweiWu

LGTM!

js-jankisalvi added 5 commits July 11, 2024 18:16

initial commit

6edb1f5

updated get, find, delete and update rule api docs

607c64d

update rule api schema

43e7451

added response details to OAS

ee159ae

update mute and unmute alert APIs

c235096

js-jankisalvi added release_note:skip Skip the PR/issue when compiling release notes Team:ResponseOps Platform ResponseOps team (formerly the Cases and Alerting teams) t// Feature:Alerting/RulesFramework Issues related to the Alerting Rules Framework v8.16.0 labels Jul 16, 2024

js-jankisalvi self-assigned this Jul 16, 2024

js-jankisalvi requested a review from a team as a code owner July 16, 2024 14:34

js-jankisalvi added 2 commits July 16, 2024 15:34

Merge branch 'main' into oas-schema-rules-api

f2e7fa5

Merge branch 'main' into oas-schema-rules-api

b846f9b

js-jankisalvi commented Jul 16, 2024

View reviewed changes

js-jankisalvi requested review from JiaweiWu, adcoelho, cnasikas and lcawl July 16, 2024 15:29

cnasikas approved these changes Jul 17, 2024

View reviewed changes

cnasikas mentioned this pull request Jul 17, 2024

[ResponseOps][Rules] OAS schema registration for Rule APIs #187574

Closed

wrap params with request object in delete and mute alert api

0da77e3

cnasikas mentioned this pull request Jul 17, 2024

[ResponseOps][Rules] Add 4xx and 5xx responses to OAS #188514

Closed

adcoelho reviewed Jul 18, 2024

View reviewed changes

x-pack/plugins/alerting/server/routes/rule/apis/create/create_rule_route.ts Outdated Show resolved Hide resolved

use response schema v1

800b759

adcoelho approved these changes Jul 19, 2024

View reviewed changes

JiaweiWu reviewed Jul 22, 2024

View reviewed changes

js-jankisalvi and others added 2 commits July 23, 2024 09:25

Merge branch 'main' into oas-schema-rules-api

81196f6

update response with description

6cf0ed7

lcawl approved these changes Jul 23, 2024

View reviewed changes

PR feedback

b05aff0

JiaweiWu approved these changes Jul 24, 2024

View reviewed changes

js-jankisalvi merged commit 9422ef9 into elastic:main Jul 24, 2024

kibanamachine added the backport:skip This PR does not require backporting label Jul 24, 2024

js-jankisalvi deleted the oas-schema-rules-api branch July 24, 2024 16:06

lcawl mentioned this pull request Aug 28, 2024

[ResponseOps][Connectors] Add descriptions for OpenAPI responses #191678

Merged

Conversation

js-jankisalvi commented Jul 16, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

How to test

Uh oh!

elasticmachine commented Jul 16, 2024

Uh oh!

js-jankisalvi Jul 16, 2024

Choose a reason for hiding this comment

Uh oh!

adcoelho Jul 19, 2024

Choose a reason for hiding this comment

Uh oh!

cnasikas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

elasticmachine commented Jul 18, 2024

💚 Build Succeeded

Metrics [docs]

History

Uh oh!

adcoelho left a comment

Choose a reason for hiding this comment

Uh oh!

JiaweiWu left a comment

Choose a reason for hiding this comment

Uh oh!

JiaweiWu Jul 22, 2024

Choose a reason for hiding this comment

Uh oh!

JiaweiWu Jul 22, 2024

Choose a reason for hiding this comment

Uh oh!

js-jankisalvi Jul 23, 2024

Choose a reason for hiding this comment

Uh oh!

lcawl Jul 23, 2024

Choose a reason for hiding this comment

Uh oh!

JiaweiWu Jul 22, 2024

Choose a reason for hiding this comment

Uh oh!

js-jankisalvi commented Jul 23, 2024

Uh oh!

lcawl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kibana-ci commented Jul 23, 2024

💛 Build succeeded, but was flaky

Failed CI Steps

Metrics [docs]

History

Uh oh!

JiaweiWu left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

js-jankisalvi commented Jul 16, 2024 •

edited

Loading