[alerting][docs] document alert/action types, and JSON structures needed for HTTP APIs

[pmuellr]

A customer pointed out that our shiny new API docs are missing some important aspects - the rule/connector-type id's that are valid for use, and the JSON structures required for alert params, and action config/secrets/params.

We should get these added to the HTTP documents, but I'm not sure it's worth doing that if we do it manually, since I'd guess we'd forget to update them when they change (though hopefully they don't change much!) or forget to add the info for new alert/action types.

So I'd like to see if we could automate this, somehow.

[elasticmachine]

Pinging @elastic/kibana-alerting-services (Team:Alerting Services)

[gmmorris]

Are we sure we want to document all types?
I suspect some solutions would prefer users don't create their Rule types via the APIs....

Might be worth focussing on Stack Rules & Connectors, rather than all 🤔
But I'm not sure.... probably best to ask the different Rule type implementors.

[pmuellr]

Are we sure we want to document all types?

I'd think that by default they should all be documented - we could choose to not document some, but then it's just security by obscurity, since we ship the code ...

Might be worth focussing on Stack Rules & Connectors, rather than all 🤔
But I'm not sure.... probably best to ask the different Rule type implementors.

The alerting team would only do the Stack rules and connectors, solutions would need to doc their own presumably, and then I guess they could choose to not document ...

[pmuellr]

I created some docs on APM and uptime alerts - I just scraped the schema-config from the code, so not great, but not horrible. At least this is the bare minimum of the kind of data we'd want to document.

alert-types-and-params.md.txt
alert.types.and.params.pdf

[pmuellr]

A customer noted that they didn't understand the complete flow of operations, so we should somehow doc that. Basically, that you need to create an action first, and then use it's id in the action section of the alert parameters to reference it.

[pmuellr]

also see: #98456 which is asking for just the rule type ids - the params will be the next thing that users of the HTTP APIs will need ...

[pmuellr]

I had assigned this to myself, as I wanted to see if I could take a crack at doing something, but ... it's hard. I'm going to unassign myself and add a discuss label, since I think there's some discussion-worthy items here>

• I'm not sure whether the existing documentation "shape" is really amenable to documenting these shapes. For example, the definition for the create rule definition is already somewhat complex, since the data passed in takes object field values, with more properties. It feels like the potential complexity of alert / action params / config / secrets won't work out so well, if doc'd that way.

• The current documentation is clearly generated by hand, but it would be preferable to have it generated from code, so the documentation would always match the code. Otherwise, we'll probably find alert implementors forgetting to update the docs when the code is changed.

• Because alerting allows rule type implementors to validate their own data, we have at least two different "validators" in use - Kibana's own config-schema package and io-ts. Even if we had just one of those, I don't believe we have a way of "generating doc" to describe those structures for either package.

• There is an open issue in Kibana to provide / generate OpenAPI specs for the Kibana API. If we end up implementing this, then the alerting / connector params / config / secrets shape definitions would become part of this (presumably), since they are part of the create / update alerting rule / connector APIs. At that point, we will presumably have "nice" doc for these.

• Another route is to somehow make use of the "dev docs" work which is generating some doc from code now. Due to the multiple validators in use, and the way they generate TypeScript types, we may have to have an intermediate layer of explicit TypeScript types which match what the validators generate (and we could probably have some way of validating that they are both the same, as far as the TypeScript compiler goes).

• I think ideally I'd like to see us generating JSON schema for these, which would need to be provided by rule implementors, and would be used as at least a first pass at validating the data. And then we could generate documentation from that schema. Note that JSON schema is used by OpenAPI as the primary data definition scheme. Use of OpenAPI assumes you are describing your data in JSON schema. It could be that building a story on first JSON schema would put us on a good path if we eventually want to have OpenAPI specs.

• One option in lieu of "generating documentation" in the usual sense that we are familiar with in elastic (for instance, from asciidoc), would be to allow Kibana to generate the documentation as a new endpoint. In fact, it would probably be useful in some scenarios to have the JSON schema itself available from the Kibana server, so it could be used by other API processors.

In the mean time, we still occasionally get requests from users for this, but not a lot, so I think we can live for a little while longer handing out the data from this comment, or otherwise generating it ad hoc.