Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 1 commit into from
Oct 31, 2024
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52,827 changes: 52,827 additions & 0 deletions oas_docs/output/kibana.serverless.yaml
View file
Open in desktop

Large diffs are not rendered by default.

1,167 changes: 1,076 additions & 91 deletions oas_docs/output/kibana.yaml
View file
Open in desktop

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion oas_docs/scripts/merge_ess_oas.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion oas_docs/scripts/merge_ess_oas_staging.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion oas_docs/scripts/merge_serverless_oas.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion oas_docs/scripts/merge_serverless_oas_staging.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
186 changes: 0 additions & 186 deletions x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml
View file
Open in desktop

This file was deleted.

26 changes: 18 additions & 8 deletions x-pack/plugins/observability_solution/apm/docs/openapi/apm/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Loading