elastic · kibanamachine · Dec 12, 2022 · Dec 12, 2022
diff --git a/docs/api-generated/README.md b/docs/api-generated/README.md
@@ -14,6 +14,8 @@ or a similar tool that can generate HTML output from OAS.
 . Generate HTML output. For example:
 
   ```
+  openapi-generator-cli generate -g html -i $GIT_HOME/kibana/x-pack/plugins/alerting/docs/openapi/bundled.yaml -o $GIT_HOME/kibana/docs/api-generated/rules -t $GIT_HOME/kibana/docs/api-generated/template
+
   openapi-generator-cli generate -g html -i $GIT_HOME/kibana/x-pack/plugins/cases/docs/openapi/bundled.yaml -o $GIT_HOME/kibana/docs/api-generated/cases -t $GIT_HOME/kibana/docs/api-generated/template
 
   openapi-generator-cli generate -g html -i $GIT_HOME/kibana/x-pack/plugins/actions/docs/openapi/bundled.yaml -o $GIT_HOME/kibana/docs/api-generated/connectors -t $GIT_HOME/kibana/docs/api-generated/template
@@ -23,6 +25,7 @@ or a similar tool that can generate HTML output from OAS.
 
 . Rename the output files. For example:
   ```
+   mv $GIT_HOME/kibana/docs/api-generated/rules/index.html $GIT_HOME/kibana/docs/api-generated/rules/rule-apis-passthru.asciidoc
   mv $GIT_HOME/kibana/docs/api-generated/cases/index.html $GIT_HOME/kibana/docs/api-generated/cases/case-apis-passthru.asciidoc
   mv $GIT_HOME/kibana/docs/api-generated/connectors/index.html $GIT_HOME/kibana/docs/api-generated/connectors/connector-apis-passthru.asciidoc
   mv $GIT_HOME/kibana/docs/api-generated/machine-learning/index.html $GIT_HOME/kibana/docs/api-generated/machine-learning/ml-apis-passthru.adoc

diff --git a/docs/api-generated/rules/rule-apis-passthru.asciidoc b/docs/api-generated/rules/rule-apis-passthru.asciidoc
diff --git a/docs/api-generated/rules/rule-apis.asciidoc b/docs/api-generated/rules/rule-apis.asciidoc
@@ -0,0 +1,10 @@
+[[rule-apis]]
+== Alert and rule APIs
+
+preview::[]
+
+////
+This file includes content that has been generated from https://github.com/elastic/kibana/tree/main/x-pack/plugins/alerting/docs/openapi. Any modifications required must be done in that open API specification.
+////
+
+include::rule-apis-passthru.asciidoc[]
diff --git a/docs/api/alerting/find_rules.asciidoc b/docs/api/alerting/find_rules.asciidoc
@@ -6,6 +6,12 @@
 
 Retrieve a paginated set of rules based on condition.
 
+[NOTE]
+====
+For the most up-to-date API details, refer to the
+{kib-repo}/tree/{branch}/x-pack/plugins/alerting/docs/openapi[open API specification]. For a preview, check out <<rule-apis>>.
+====
+
 [[find-rules-api-request]]
 === {api-request-title}
 
@@ -105,40 +111,49 @@ The API returns the following:
 --------------------------------------------------
 {
   "page": 1,
-  "per_page": 10,
   "total": 1,
-  "data": [
-    {
-      "id": "0a037d60-6b62-11eb-9e0d-85d233e3ee35",
-      "notify_when": "onActionGroupChange",
+  "per_page": 10,
+  "data": [{
+    "id": "b530fed0-74f5-11ed-9801-35303b735aef",
+    "name": "cluster_health_rule",
+    "consumer": "alerts",
+    "enabled": true,
+    "tags": ["cluster","health"],
+    "throttle": null,
+    "schedule": {"interval":"1m"},
+    "params": {},
+    "rule_type_id": "monitoring_alert_cluster_health",
+    "created_by": "elastic",
+    "updated_by": "elastic",
+    "created_at": "2022-12-05T23:36:58.284Z",
+    "updated_at": "2022-12-05T23:36:58.284Z",
+    "api_key_owner": "elastic",
+    "notify_when": "onActiveAlert",
+    "mute_all": false,
+    "muted_alert_ids": [],
+    "scheduled_task_id": "b530fed0-74f5-11ed-9801-35303b735aef",
+    "execution_status": {
+      "status": "ok",
+      "last_execution_date": "2022-12-06T00:09:31.882Z",
+      "last_duration": 42
+    },
+    "actions": [{
+      "group": "default",
+      "id": "9dca3e00-74f5-11ed-9801-35303b735aef",
       "params": {
-        "aggType": "avg",
-      },
-      "consumer": "alerts",
-      "rule_type_id": "test.rule.type",
-      "schedule": {
-        "interval": "1m"
+        "level": "info",
+        "message": "{{context.internalFullMessage}}"
       },
-      "actions": [],
-      "tags": [],
-      "name": "my test rule",
-      "enabled": true,
-      "throttle": null,
-      "api_key_owner": "elastic",
-      "created_by": "elastic",
-      "updated_by": "elastic",
-      "mute_all": false,
-      "muted_alert_ids": [],
-      "updated_at": "2021-02-10T05:37:19.086Z",
-      "created_at": "2021-02-10T05:37:19.086Z",
-      "scheduled_task_id": "0b092d90-6b62-11eb-9e0d-85d233e3ee35",
-      "execution_status": {
-        "last_execution_date": "2021-02-10T17:55:14.262Z",
-        "status": "ok",
-        "last_duration": 384
-      }
-    }
-  ]
+      "connector_type_id": ".server-log"
+    }],
+    "last_run":{
+      "alerts_count": {"new": 0,"ignored": 0,"recovered": 0,"active": 0},
+      "outcome_msg": null,
+      "warning": null,
+      "outcome": "succeeded"
+    },
+    "next_run": "2022-12-06T00:10:31.811Z"
+  }]
 }
 --------------------------------------------------
 

diff --git a/docs/apis.asciidoc b/docs/apis.asciidoc
@@ -13,4 +13,5 @@ version of the specification is 3.0. For more information, go to https://openapi
 
 include::api-generated/cases/case-apis.asciidoc[]
 include::api-generated/connectors/connector-apis.asciidoc[]
-include::api-generated/machine-learning/ml-apis.asciidoc[]
+include::api-generated/machine-learning/ml-apis.asciidoc[]
+include::api-generated/rules/rule-apis.asciidoc[]
diff --git a/x-pack/plugins/alerting/docs/openapi/README.md b/x-pack/plugins/alerting/docs/openapi/README.md
@@ -0,0 +1,34 @@
+# OpenAPI (Experimental)
+
+The current self-contained spec file is [as JSON](https://raw.githubusercontent.com/elastic/kibana/master/x-pack/plugins/cases/common/openapi/bundled.json) or [as YAML](https://raw.githubusercontent.com/elastic/kibana/master/x-pack/plugins/cases/common/openapi/bundled.yaml) and can be used for online tools like those found at https://openapi.tools/. 
+This spec is experimental and may be incomplete or change later.
+
+A guide about the openApi specification can be found at [https://swagger.io/docs/specification/about/](https://swagger.io/docs/specification/about/).
+
+## The `openapi` folder
+
+* `entrypoint.yaml` is the overview file which pulls together all the paths and components.
+* [Paths](paths/README.md): this defines each endpoint.  A path can have one operation per http method.
+* [Components](components/README.md): Reusable components
+
+## Tools
+
+It is possible to validate the docs before bundling them with the following
+command in the `x-pack/plugins/alerting/docs/openapi/` folder:
+
+  ```
+    npx swagger-cli validate entrypoint.yaml
+  ```
+
+Then you can generate the `bundled` files by running the following commands:
+
+  ```
+    npx @redocly/cli bundle entrypoint.yaml --output bundled.yaml --ext yaml
+    npx @redocly/cli bundle entrypoint.yaml --output bundled.json --ext json
+  ```
+
+You can run additional linting with the following command:
+
+  ```
+     npx @redocly/cli lint bundled.json
+  ```