github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-24 09:48:58 -04:00
Code Issues Projects Releases Packages Wiki Activity

[OAS] Generate OpenAPI document for Kibana APIs (#188613)

Browse source
This commit is contained in:
Lisa Cawley 2024-07-18 14:26:40 -07:00 • committed by GitHub
parent 6bfe360726
commit 15401de051
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 12234 additions and 23 deletions
Download patch file Download diff file Expand all files Collapse all files

7
oas_docs/README.md
View file

@ -1,4 +1,7 @@
The `bundle.json` and `bundle.serverless.json` files are generated automatically.
The `kibana.openapi.serverless.yaml` file is a temporary OpenAPI document created by joining some manually-maintained files.
To create it and lint it, run `make api-docs` and `make api-docs-lint`.
The `output/kibana.serverless.yaml` file is a temporary OpenAPI document created by joining some manually-maintained files.
To create it and lint it, run `make api-docs` or `make api-docs-serverless` and `make api-docs-lint` or `make api-docs-lint-serverless`.
The `output/kibana.yaml` file is a temporary OpenAPI document created by joining some manually-maintained files.
To create it and lint it, run `make api-docs` or `make api-docs-stateful` and `make api-docs-lint` or `make api-docs-lint-stateful`.

47
oas_docs/kibana.info.yaml Normal file
View file

@ -0,0 +1,47 @@
openapi: 3.0.3
info:
title: Kibana APIs
description: |
The Kibana REST APIs enable you to manage resources such as connectors, data views, and saved objects.
The API calls are stateless.
Each request that you make happens in isolation from other calls and must include all of the necessary information for Kibana to fulfill the
request.
API requests return JSON output, which is a format that is machine-readable and works well for automation.
To interact with Kibana APIs, use the following operations:
- GET: Fetches the information.
- PATCH: Applies partial modifications to the existing information.
- POST: Adds new information.
- PUT: Updates the existing information.
- DELETE: Removes the information.
You can prepend any Kibana API endpoint with `kbn:` and run the request in **Dev Tools → Console**.
For example:
```
GET kbn:/api/data_views
```
version: "1.0.2"
license:
name: Elastic License 2.0
url: https://www.elastic.co/licensing/elastic-license
contact:
name: Kibana Team
# servers:
# - url: https://{kibana_url}
# variables:
# kibana_url:
# default: localhost:5601
# security:
# - apiKeyAuth: []
# components:
# securitySchemes:
# apiKeyAuth:
# type: apiKey
# in: header
# name: Authorization
# description: >
# These APIs use key-based authentication.
# You must create an API key and use the encoded value in the request header.
# For example: `Authorization: ApiKey base64AccessApiKey`

32
oas_docs/makefile
View file

@ -14,12 +14,36 @@
# permission is obtained from Elasticsearch B.V.
.PHONY: api-docs
api-docs: ## Generate kibana.serverless.yaml
@npx @redocly/cli join "kibana.info.serverless.yaml" "../x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml" "../x-pack/plugins/actions/docs/openapi/bundled_serverless.yaml" "../src/plugins/data_views/docs/openapi/bundled.yaml" "../x-pack/plugins/ml/common/openapi/ml_apis_serverless.yaml" "../packages/core/saved-objects/docs/openapi/bundled_serverless.yaml" "../x-pack/plugins/observability_solution/slo/docs/openapi/slo/bundled.yaml" -o "kibana.serverless.yaml" --prefix-components-with-info-prop title
api-docs: ## Generate kibana.serverless.yaml and kibana.yaml
@npx @redocly/cli join "kibana.info.serverless.yaml" "../x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml" "../x-pack/plugins/actions/docs/openapi/bundled_serverless.yaml" "../src/plugins/data_views/docs/openapi/bundled.yaml" "../x-pack/plugins/ml/common/openapi/ml_apis_serverless.yaml" "../packages/core/saved-objects/docs/openapi/bundled_serverless.yaml" "../x-pack/plugins/observability_solution/slo/docs/openapi/slo/bundled.yaml" -o "output/kibana.serverless.yaml" --prefix-components-with-info-prop title
@npx @redocly/cli join "kibana.info.yaml" "../x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml" "../x-pack/plugins/actions/docs/openapi/bundled.yaml" "../src/plugins/data_views/docs/openapi/bundled.yaml" "../x-pack/plugins/ml/common/openapi/ml_apis.yaml" "../packages/core/saved-objects/docs/openapi/bundled.yaml" "../x-pack/plugins/observability_solution/slo/docs/openapi/slo/bundled.yaml" -o "output/kibana.yaml" --prefix-components-with-info-prop title
.PHONY: api-docs-stateful
api-docs-stateful: ## Generate only kibana.yaml
@npx @redocly/cli join "kibana.info.yaml" "../x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml" "../x-pack/plugins/actions/docs/openapi/bundled.yaml" "../src/plugins/data_views/docs/openapi/bundled.yaml" "../x-pack/plugins/ml/common/openapi/ml_apis.yaml" "../packages/core/saved-objects/docs/openapi/bundled.yaml" "../x-pack/plugins/observability_solution/slo/docs/openapi/slo/bundled.yaml" -o "output/kibana.yaml" --prefix-components-with-info-prop title
# Temporarily omit "../x-pack/plugins/alerting/docs/openapi/bundled.yaml" and "../x-pack/plugins/cases/docs/openapi/bundled.yaml" due to OAS version
# Temporarily omit "../x-pack/plugins/fleet/common/openapi/bundled.yaml" due to internals tag and tag sorting
.PHONY: api-docs-serverless
api-docs-serverless: ## Generate only kibana.serverless.yaml
@npx @redocly/cli join "kibana.info.serverless.yaml" "../x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml" "../x-pack/plugins/actions/docs/openapi/bundled_serverless.yaml" "../src/plugins/data_views/docs/openapi/bundled.yaml" "../x-pack/plugins/ml/common/openapi/ml_apis_serverless.yaml" "../packages/core/saved-objects/docs/openapi/bundled_serverless.yaml" "../x-pack/plugins/observability_solution/slo/docs/openapi/slo/bundled.yaml" -o "output/kibana.serverless.yaml" --prefix-components-with-info-prop title
.PHONY: api-docs-lint
api-docs-lint: ## Run spectral API docs linter
@npx @stoplight/spectral-cli lint "kibana.serverless.yaml" --ruleset ".spectral.yaml"
api-docs-lint: ## Run spectral API docs linter
@npx @stoplight/spectral-cli lint "output/kibana.serverless.yaml" --ruleset ".spectral.yaml"
@npx @stoplight/spectral-cli lint "output/kibana.yaml" --ruleset ".spectral.yaml"
.PHONY: api-docs-lint-stateful
api-docs-lint-stateful: ## Run spectral API docs linter on kibana.yaml
@npx @stoplight/spectral-cli lint "output/kibana.yaml" --ruleset ".spectral.yaml"
.PHONY: api-docs-lint-serverless
api-docs-lint-serverless: ## Run spectral API docs linter on kibana.serverless.yaml
@npx @stoplight/spectral-cli lint "output/kibana.serverless.yaml" --ruleset ".spectral.yaml"
.PHONY: api-docs-overlay-stateful
api-docs-overlay-stateful: ## Run spectral API docs linter on kibana.serverless.yaml
@npx bump overlay "output/kibana.yaml" "overlays/kibana.overlays.yaml" > "output/kibana.new.yaml"
help: ## Display help
@awk 'BEGIN {FS = ":.*##"; printf "Usage:\n make \033[36m<target>\033[0m\n"} /^[a-zA-Z_-]+:.*?##/ { printf " \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)

80
oas_docs/kibana.serverless.yaml → oas_docs/output/kibana.serverless.yaml
View file

@ -1,26 +1,50 @@
openapi: 3.0.3
info:
title: Kibana Serverless APIs
description: |
description: >
**Technical preview**
This functionality is in technical preview and may be changed or removed in
a future release.
Elastic will work to fix any issues, but features in technical preview are
not subject to the support SLA of official GA features.
The Kibana REST APIs for Elastic serverless enable you to manage resources
such as connectors, data views, and saved objects. The API calls are
stateless. Each request that you make happens in isolation from other calls
and must include all of the necessary information for Kibana to fulfill the
request. API requests return JSON output, which is a format that is
machine-readable and works well for automation.
To interact with Kibana APIs, use the following operations:
- GET: Fetches the information.
- POST: Adds new information.
- PUT: Updates the existing information.
- DELETE: Removes the information.
You can prepend any Kibana API endpoint with `kbn:` and run the request in
**Dev Tools → Console**. For example:
```
GET kbn:/api/data_views
```
version: 1.0.2
license:
@ -76,6 +100,7 @@ paths:
post:
summary: Create an APM agent key
description: Create a new agent key for APM.
operationId: createAgentKey
tags:
- APM agent keys
requestBody:
@ -117,6 +142,7 @@ paths:
get:
summary: Search for annotations
description: Search for annotations related to a specific service.
operationId: getAnnotation
tags:
- APM annotations
parameters:
@ -171,6 +197,7 @@ paths:
post:
summary: Create a service annotation
description: Create a new annotation for a specific service.
operationId: createAnnotation
tags:
- APM annotations
parameters:
@ -1246,13 +1273,13 @@ paths:
summary: Update data view fields metadata in the default space
operationId: updateFieldsMetadataDefault
description: >
Update fields presentation metadata such as count, customLabel and
format. This functionality is in technical preview and may be changed or
removed in a future release. Elastic will work to fix any issues, but
features in technical preview are not subject to the support SLA of
official GA features. You can update multiple fields in one request.
Updates are merged with persisted metadata. To remove existing metadata,
specify null as the value.
Update fields presentation metadata such as count, customLabel,
customDescription, and format. This functionality is in technical
preview and may be changed or removed in a future release. Elastic will
work to fix any issues, but features in technical preview are not
subject to the support SLA of official GA features. You can update
multiple fields in one request. Updates are merged with persisted
metadata. To remove existing metadata, specify null as the value.
tags:
- data views
parameters:
@ -3324,7 +3351,7 @@ components:
description: >
The generative artificial intelligence model for Amazon Bedrock to
use. Current support is for the Anthropic Claude models.
default: anthropic.claude-3-sonnet-20240229-v1:0
default: anthropic.claude-3-5-sonnet-20240620-v1:0
Connectors_secrets_properties_bedrock:
title: Connector secrets properties for an Amazon Bedrock connector
description: Defines secrets for connectors when type is `.bedrock`.
@ -3356,7 +3383,7 @@ components:
description: >-
The generative artificial intelligence model for Google Gemini to
use.
default: gemini-1.5-pro-preview-0409
default: gemini-1.5-pro-001
gcpRegion:
type: string
description: The GCP region where the Vertex AI endpoint enabled.
@ -3594,7 +3621,7 @@ components:
The host name of the service provider. If the `service` is
`elastic_cloud` (for Elastic Cloud notifications) or one of
Nodemailer's well-known email service providers, this property is
ignored. If `service` is `other`, this property must be defined.
ignored. If `service` is `other`, this property must be defined.
type: string
oauthTokenUrl:
type: string
@ -3604,7 +3631,7 @@ components:
The port to connect to on the service provider. If the `service` is
`elastic_cloud` (for Elastic Cloud notifications) or one of
Nodemailer's well-known email service providers, this property is
ignored. If `service` is `other`, this property must be defined.
ignored. If `service` is `other`, this property must be defined.
type: integer
secure:
description: >
@ -5272,7 +5299,7 @@ components:
type: boolean
description: >
Indicates whether it is a preconfigured connector. If true, the `config`
and `is_missing_secrets` properties are omitted from the response.
and `is_missing_secrets` properties are omitted from the response.
example: false
Connectors_is_system_action:
type: boolean
@ -5780,6 +5807,17 @@ components:
Data_views_fieldattrs:
type: object
description: A map of field attributes by field name.
properties:
count:
type: integer
description: Popularity count for the field.
customDescription:
type: string
description: Custom description for the field.
maxLength: 300
customLabel:
type: string
description: Custom label for the field.
Data_views_fieldformats:
type: object
description: A map of field formats by field name.
@ -5835,7 +5873,9 @@ components:
allowNoIndex:
$ref: '#/components/schemas/Data_views_allownoindex'
fieldAttrs:
$ref: '#/components/schemas/Data_views_fieldattrs'
type: object
additionalProperties:
$ref: '#/components/schemas/Data_views_fieldattrs'
fieldFormats:
$ref: '#/components/schemas/Data_views_fieldformats'
fields:
@ -5877,7 +5917,9 @@ components:
allowNoIndex:
$ref: '#/components/schemas/Data_views_allownoindex'
fieldAttrs:
$ref: '#/components/schemas/Data_views_fieldattrs'
type: object
additionalProperties:
$ref: '#/components/schemas/Data_views_fieldattrs'
fieldFormats:
$ref: '#/components/schemas/Data_views_fieldformats'
fields:
@ -8594,11 +8636,15 @@ components:
data_view_id: ff959d40-b880-11e8-a6d9-e546fe2bba5f
force: true
Data_views_update_field_metadata_request:
summary: Set popularity count for field foo.
summary: Update multiple metadata fields.
value:
fields:
foo:
field1:
count: 123
customLabel: Field 1 label
field2:
customLabel: Field 2 label
customDescription: Field 2 description
Data_views_create_runtime_field_request:
summary: Create a runtime field.
value:

12058
oas_docs/output/kibana.yaml Normal file
View file

File diff suppressed because it is too large Load diff

33
oas_docs/overlays/kibana.overlays.yaml Normal file
View file

@ -0,0 +1,33 @@
# overlays.yaml
overlay: 1.0.0
info:
title: Overlays for the Kibana API document
version: 0.0.1
actions:
- target: '$.servers.*'
description: Remove all servers so we can add our own.
remove: true
- target: '$.servers'
description: Add server into the now empty server array.
update:
- url: https://{kibana_url}
variables:
kibana_url:
default: localhost:5601
# - target: '$.components.securitySchemes'
# description: Remove all security schemes so we can add our own.
# remove: true
# - target: '$.components'
# description: Add security schemes
# update:
# securitySchemes:
# basicAuth:
# type: http
# scheme: basic
# apiKeyAuth:
# type: apiKey
# in: header
# name: Authorization
# description: 'e.g. Authorization: ApiKey base64AccessApiKey'
# - target: '$.paths["/api/actions/connector"][*].security'
# remove: true