OpenAPI docs for APM UI APIs - manual backport to 8.x (#198550)

## Summary Manually backport #197946 into `8.x`.
elastic · Oct 31, 2024 · fbee293 · fbee293
1 parent 5d44f8c
commit fbee293
Show file tree

Hide file tree

Showing 53 changed files with 58,073 additions and 289 deletions.
diff --git a/oas_docs/output/kibana.serverless.yaml b/oas_docs/output/kibana.serverless.yaml
diff --git a/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml
diff --git a/oas_docs/scripts/merge_ess_oas.js b/oas_docs/scripts/merge_ess_oas.js
@@ -23,7 +23,7 @@ const { REPO_ROOT } = require('@kbn/repo-info');
       `${REPO_ROOT}/x-pack/plugins/fleet/common/openapi/bundled.yaml`,
 
       // Observability Solution
-      `${REPO_ROOT}/x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml`,
+      `${REPO_ROOT}/x-pack/plugins/observability_solution/apm/docs/openapi/apm/bundled.yaml`,
       `${REPO_ROOT}/x-pack/plugins/observability_solution/slo/docs/openapi/slo/bundled.yaml`,
 
       // Security solution

diff --git a/oas_docs/scripts/merge_ess_oas_staging.js b/oas_docs/scripts/merge_ess_oas_staging.js
@@ -23,7 +23,7 @@ const { REPO_ROOT } = require('@kbn/repo-info');
       `${REPO_ROOT}/x-pack/plugins/fleet/common/openapi/bundled.yaml`,
 
       // Observability Solution
-      `${REPO_ROOT}/x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml`,
+      `${REPO_ROOT}/x-pack/plugins/observability_solution/apm/docs/openapi/apm/bundled.yaml`,
       `${REPO_ROOT}/x-pack/plugins/observability_solution/slo/docs/openapi/slo/bundled.yaml`,
 
       // Security solution

diff --git a/oas_docs/scripts/merge_serverless_oas.js b/oas_docs/scripts/merge_serverless_oas.js
@@ -21,7 +21,7 @@ const { REPO_ROOT } = require('@kbn/repo-info');
       `${REPO_ROOT}/x-pack/plugins/fleet/common/openapi/bundled.yaml`,
 
       // Observability Solution
-      `${REPO_ROOT}/x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml`,
+      `${REPO_ROOT}/x-pack/plugins/observability_solution/apm/docs/openapi/apm/bundled.yaml`,
       `${REPO_ROOT}/x-pack/plugins/observability_solution/slo/docs/openapi/slo/bundled.yaml`,
 
       // Security solution

diff --git a/oas_docs/scripts/merge_serverless_oas_staging.js b/oas_docs/scripts/merge_serverless_oas_staging.js
@@ -21,7 +21,7 @@ const { REPO_ROOT } = require('@kbn/repo-info');
       `${REPO_ROOT}/x-pack/plugins/fleet/common/openapi/bundled.yaml`,
 
       // Observability Solution
-      `${REPO_ROOT}/x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml`,
+      `${REPO_ROOT}/x-pack/plugins/observability_solution/apm/docs/openapi/apm/bundled.yaml`,
       `${REPO_ROOT}/x-pack/plugins/observability_solution/slo/docs/openapi/slo/bundled.yaml`,
 
       // Security solution

diff --git a/x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml b/x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml
diff --git a/x-pack/plugins/observability_solution/apm/docs/openapi/apm/README.md b/x-pack/plugins/observability_solution/apm/docs/openapi/apm/README.md
@@ -2,16 +2,26 @@
 
 This directory contains [OpenAPI specifications](https://swagger.io/specification/) for the [APM app API](https://www.elastic.co/guide/en/kibana/current/apm-api.html) in Kibana.
 
-Included: 
+# OpenAPI (Experimental)
 
-* [Agent Configuration API](https://www.elastic.co/guide/en/kibana/current/agent-config-api.html)
-* [Annotation API](https://www.elastic.co/guide/en/kibana/current/apm-annotation-api.html)
+The current self-contained spec file is available as `bundled.json` or `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.
 
-Not included:
+A guide about the openApi specification can be found at [https://swagger.io/docs/specification/about/](https://swagger.io/docs/specification/about/).
 
-* [APM agent Key API](https://www.elastic.co/guide/en/kibana/current/agent-key-api.html)
-* [RUM source map API](https://www.elastic.co/guide/en/kibana/current/rum-sourcemap-api.html)
+## The `openapi` folder
 
-The specifications for the included APIs are in the apm.yaml file in this directory.
+* `entrypoint.yaml` is the overview file which pulls together all the paths and components.
+* [Paths](paths/README.md): Defines each endpoint.  A path can have one operation per http method.
+* [Components](components/README.md): Defines reusable components.
 
-These specifications are manually written. The missing ones will be included in the future.
+## Tools
+
+Generate the `bundled` files by running the following commands:
+
+```bash
+npx @redocly/cli bundle entrypoint.yaml --output bundled.yaml --ext yaml
+npx @redocly/cli bundle entrypoint.yaml --output bundled.json --ext json
+```
+
+Then join these files with the rest of the Kibana APIs per `oas_docs/README.md`