[DOCS] Create open API specification for find rules

[lcawl]

Summary

Relates to #137240, #144566

This PR adds the new last_run and next_run properties to the find rule API docs.

It also creates the open API specification for that endpoint and generates a preview in the Kibana appendix. Some of the descriptions for response properties are obtained from https://github.com/elastic/kibana/blob/main/x-pack/plugins/alerting/README.md

[github-actions]

Documentation preview:

• ✨ Changed pages

[elasticmachine]

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

[szabosteve]

LGTM!

[pmuellr]

The data field response from the find API will end up being the "rule shape" that is returned from several APIs - I think for that shape, we'll want to figure out how to describe that shape separately, and then refer to that description from here.
Ideally the doc would just be a link to the type, so the resulting doc for the API would be a lot smaller.

Wondering if we should add one more API - maybe GET /api/alerting/rule/{id}, which is pretty simple, so we can get the structure working. I'm not sure there's any other "shared structures" like that. Or that could be a follow-on PR ...

We'll also have to figure out what we want to do eventually with actions[X].params. Would be nice to point, somehow, to all the potential shapes, which are based on actions[X].connector_type_id(each connector type defines a different shape).

Or maybe we want some other structure for these.

[guskovaue]

Hi, @lcawl !

Looked at docs preview:

And see Query Parameter under each parameter. Is it expected?

[lcawl]

And see Query Parameter under each parameter. Is it expected?

You're right, that's unnecessary, so I'll add it to our list of known issues with this generator tool. Hopefully we won't be using it for too long, however, and this wouldn't be one that I'd consider a blocker.

[lcawl]

The data field response from the find API will end up being the "rule shape" that is returned from several APIs - I think for that shape, we'll want to figure out how to describe that shape separately, and then refer to that description from here. Ideally the doc would just be a link to the type, so the resulting doc for the API would be a lot smaller.

For other endpoints, if there are objects / arrays etc that are used in multiple places, we've ended up putting them in reusable "schemas" like the ones for cases here: https://github.com/elastic/kibana/tree/main/x-pack/plugins/cases/docs/openapi/components/schemas I fully expect that as I get more rule API specs generated, we'll have re-used schemas here too.

An advantage of having them fully described in the spec rather than just pointing elsewhere is that they're then tested against the examples that we provide in the spec (e.g. it tells me if I've got a null in a field that's not nullable).

Wondering if we should add one more API - maybe GET /api/alerting/rule/{id}, which is pretty simple, so we can get the structure working. I'm not sure there's any other "shared structures" like that. Or that could be a follow-on PR ...

My preference would be to get one in (so all the other structure and folders are in place), then break out schema objects as needed. I was getting very big PRs which were harder to review otherwise.

We'll also have to figure out what we want to do eventually with actions[X].params. Would be nice to point, somehow, to all the potential shapes, which are based on actions[X].connector_type_id(each connector type defines a different shape).

I'm open to any level of discussions for the preferred shape and all the pertinent properties! It'll be interesting to see how much overlap there is between the connector API specs and the rule API specs (and how we can avoid any redundancies). For the cases APIs, I relied on the oneOf/anyOf/allOf functionality to group the different types of supported connector properties. I'm hoping the same will be feasible here too!

[guskovaue]

@elasticmachine merge upstream

[kibana-ci]

💚 Build Succeeded

• Buildkite Build
• Commit: ddf897a

Metrics [docs]

Unknown metric groups

ESLint disabled in files

id	before	after	diff
osquery	1	2	+1

ESLint disabled line counts

id	before	after	diff
enterpriseSearch	19	21	+2
fleet	60	66	+6
osquery	109	115	+6
securitySolution	445	451	+6
total			+20

Total ESLint disabled count

id	before	after	diff
enterpriseSearch	20	22	+2
fleet	69	75	+6
osquery	110	117	+7
securitySolution	521	527	+6
total			+21

History

• 💔 Build #93876 failed f8d03a0
• 💔 Build #93718 failed 87f6808
• 💔 Build #93354 failed 2919757
• 💚 Build #92927 succeeded b81e429

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

[kibanamachine]

💚 All backports created successfully

Status	Branch	Result
✅	8.6

Note: Successful backport PRs will be merged automatically after passing CI.

Questions ?

Please refer to the Backport tool documentation