OpenAPI docs for APM UI APIs (elastic#197946)

## Summary Closes elastic#197582 This PR adds missing OpenAPI specification for APM UI APIs. Documentation specs have been divided into files per path. See [readme](https://github.com/elastic/kibana/blob/88e55f92f91e04112e831023e163e4990018de52/x-pack/plugins/observability_solution/apm/docs/openapi/apm/README.md) for specific information.
jennypavlova · Oct 31, 2024 · e083814 · e083814
1 parent 7c9bf00
commit e083814
Show file tree

Hide file tree

Showing 51 changed files with 6,320 additions and 378 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
@@ -22,7 +22,7 @@ const { REPO_ROOT } = require('@kbn/repo-info');
       `${REPO_ROOT}/packages/core/saved-objects/docs/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
@@ -20,7 +20,7 @@ const { REPO_ROOT } = require('@kbn/repo-info');
       `${REPO_ROOT}/packages/core/saved-objects/docs/openapi/bundled_serverless.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`