github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-23 17:28:26 -04:00
Code Issues Projects Releases Packages Wiki Activity

[OAS] Combine manual and automated OpenAPI documents (#188702)

Browse source
This commit is contained in:
Lisa Cawley 2024-07-22 14:20:03 -07:00 • committed by GitHub
parent 5c4eae1286
commit 17181e6ba5
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 690 additions and 28 deletions
Download patch file Download diff file Expand all files Collapse all files

1
oas_docs/.spectral.yaml
View file

@ -24,6 +24,7 @@ rules:
# Schema
oas3-schema: error
oas2-schema: error
array-items: false
# Tags
openapi-tags: warn
openapi-tags-alphabetical: info

1
oas_docs/README.md
View file

@ -1,4 +1,5 @@
The `bundle.json` and `bundle.serverless.json` files are generated automatically.
See `node scripts/capture_oas_snapshot --help` for more info.
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`.

10
oas_docs/bundle.json
View file

@ -418,7 +418,9 @@
}
},
"summary": "Get Kibana's current status",
"tags": []
"tags": [
"system"
]
}
}
},
@ -432,5 +434,9 @@
"url": "http://localhost:5622"
}
],
"tags": []
"tags": [
{
"name": "system"
}
]
}

10
oas_docs/bundle.serverless.json
View file

@ -418,7 +418,9 @@
}
},
"summary": "Get Kibana's current status",
"tags": []
"tags": [
"system"
]
}
}
},
@ -432,5 +434,9 @@
"url": "http://localhost:5622"
}
],
"tags": []
"tags": [
{
"name": "system"
}
]
}

13
oas_docs/makefile
View file

@ -15,18 +15,18 @@
.PHONY: api-docs
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
@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" "bundle.serverless.json" --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" "bundle.json" -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
@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" "bundle.json" -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
@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" "bundle.serverless.json" --prefix-components-with-info-prop title
.PHONY: api-docs-lint
api-docs-lint: ## Run spectral API docs linter
@ -41,9 +41,10 @@ api-docs-lint-stateful: ## Run spectral API docs linter on kibana.yaml
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
.PHONY: api-docs-overlay
api-docs-overlay: ## Run spectral API docs linter on kibana.serverless.yaml
@npx bump overlay "output/kibana.yaml" "overlays/kibana.overlays.yaml" > "output/kibana.new.yaml"
@npx bump overlay "output/kibana.serverless.yaml" "overlays/kibana.overlays.yaml" > "output/kibana.serverless.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)

332
oas_docs/output/kibana.serverless.yaml
View file

@ -64,6 +64,7 @@ servers:
- url: /
- url: http://localhost:5601
description: local
- url: http://localhost:5622
tags:
- name: APM agent keys
description: >
@ -95,6 +96,8 @@ tags:
- name: slo
description: SLO APIs enable you to define, manage and track service-level objectives
x-displayName: slo
- name: system
x-displayName: system
paths:
/api/apm/agent_keys:
post:
@ -2559,6 +2562,58 @@ paths:
security:
- SLOs_basicAuth: []
- SLOs_apiKeyAuth: []
/api/status:
get:
operationId: /api/status#0
parameters:
- description: The version of the API to use
in: header
name: elastic-api-version
schema:
default: '2023-10-31'
enum:
- '2023-10-31'
type: string
- description: Set to "true" to get the response in v7 format.
in: query
name: v7format
required: false
schema:
type: boolean
- description: Set to "true" to get the response in v8 format.
in: query
name: v8format
required: false
schema:
type: boolean
responses:
'200':
content:
application/json; Elastic-Api-Version=2023-10-31:
schema:
anyOf:
- $ref: '#/components/schemas/Kibana_HTTP_APIs_core_status_response'
- $ref: >-
#/components/schemas/Kibana_HTTP_APIs_core_status_redactedResponse
description: >-
Kibana's operational status. A minimal response is sent for
unauthorized users.
'503':
content:
application/json; Elastic-Api-Version=2023-10-31:
schema:
anyOf:
- $ref: '#/components/schemas/Kibana_HTTP_APIs_core_status_response'
- $ref: >-
#/components/schemas/Kibana_HTTP_APIs_core_status_redactedResponse
description: >-
Kibana's operational status. A minimal response is sent for
unauthorized users.
summary: Get Kibana's current status
tags:
- system
security:
- Kibana_HTTP_APIs_basicAuth: []
components:
securitySchemes:
Connectors_apiKeyAuth:
@ -2600,6 +2655,13 @@ components:
in: header
name: Authorization
description: 'e.g. Authorization: ApiKey base64AccessApiKey'
Kibana_HTTP_APIs_apiKeyAuth:
in: header
name: Authorization
type: apiKey
Kibana_HTTP_APIs_basicAuth:
scheme: basic
type: http
parameters:
Connectors_kbn_xsrf:
schema:
@ -7473,6 +7535,273 @@ components:
description: The SLO instance identifier
type: string
example: 8853df00-ae2e-11ed-90af-09bb6422b258
Kibana_HTTP_APIs_core_status_redactedResponse:
additionalProperties: false
description: A minimal representation of Kibana's operational status.
properties:
status:
additionalProperties: false
properties:
overall:
additionalProperties: false
properties:
level:
description: Service status levels as human and machine readable values.
enum:
- available
- degraded
- unavailable
- critical
type: string
required:
- level
type: object
required:
- overall
type: object
required:
- status
type: object
Kibana_HTTP_APIs_core_status_response:
additionalProperties: false
description: >-
Kibana's operational status as well as a detailed breakdown of plugin
statuses indication of various loads (like event loop utilization and
network traffic) at time of request.
properties:
metrics:
additionalProperties: false
description: Metric groups collected by Kibana.
properties:
collection_interval_in_millis:
description: The interval at which metrics should be collected.
type: number
elasticsearch_client:
additionalProperties: false
description: Current network metrics of Kibana's Elasticsearch client.
properties:
totalActiveSockets:
description: Count of network sockets currently in use.
type: number
totalIdleSockets:
description: Count of network sockets currently idle.
type: number
totalQueuedRequests:
description: Count of requests not yet assigned to sockets.
type: number
required:
- totalActiveSockets
- totalIdleSockets
- totalQueuedRequests
type: object
last_updated:
description: The time metrics were collected.
type: string
required:
- elasticsearch_client
- last_updated
- collection_interval_in_millis
type: object
name:
description: Kibana instance name.
type: string
status:
additionalProperties: false
properties:
core:
additionalProperties: false
description: Statuses of core Kibana services.
properties:
elasticsearch:
additionalProperties: false
properties:
detail:
description: Human readable detail of the service status.
type: string
documentationUrl:
description: A URL to further documentation regarding this service.
type: string
level:
description: >-
Service status levels as human and machine readable
values.
enum:
- available
- degraded
- unavailable
- critical
type: string
meta:
additionalProperties: {}
description: >-
An unstructured set of extra metadata about this
service.
type: object
summary:
description: A human readable summary of the service status.
type: string
required:
- level
- summary
- meta
type: object
savedObjects:
additionalProperties: false
properties:
detail:
description: Human readable detail of the service status.
type: string
documentationUrl:
description: A URL to further documentation regarding this service.
type: string
level:
description: >-
Service status levels as human and machine readable
values.
enum:
- available
- degraded
- unavailable
- critical
type: string
meta:
additionalProperties: {}
description: >-
An unstructured set of extra metadata about this
service.
type: object
summary:
description: A human readable summary of the service status.
type: string
required:
- level
- summary
- meta
type: object
required:
- elasticsearch
- savedObjects
type: object
overall:
additionalProperties: false
properties:
detail:
description: Human readable detail of the service status.
type: string
documentationUrl:
description: A URL to further documentation regarding this service.
type: string
level:
description: Service status levels as human and machine readable values.
enum:
- available
- degraded
- unavailable
- critical
type: string
meta:
additionalProperties: {}
description: An unstructured set of extra metadata about this service.
type: object
summary:
description: A human readable summary of the service status.
type: string
required:
- level
- summary
- meta
type: object
plugins:
additionalProperties:
additionalProperties: false
properties:
detail:
description: Human readable detail of the service status.
type: string
documentationUrl:
description: A URL to further documentation regarding this service.
type: string
level:
description: >-
Service status levels as human and machine readable
values.
enum:
- available
- degraded
- unavailable
- critical
type: string
meta:
additionalProperties: {}
description: An unstructured set of extra metadata about this service.
type: object
summary:
description: A human readable summary of the service status.
type: string
required:
- level
- summary
- meta
type: object
description: A dynamic mapping of plugin ID to plugin status.
type: object
required:
- overall
- core
- plugins
type: object
uuid:
description: >-
Unique, generated Kibana instance UUID. This UUID should persist
even if the Kibana process restarts.
type: string
version:
additionalProperties: false
properties:
build_date:
description: The date and time of this build.
type: string
build_flavor:
description: >-
The build flavour determines configuration and behavior of
Kibana. On premise users will almost always run the
"traditional" flavour, while other flavours are reserved for
Elastic-specific use cases.
enum:
- serverless
- traditional
type: string
build_hash:
description: >-
A unique hash value representing the git commit of this Kibana
build.
type: string
build_number:
description: >-
A monotonically increasing number, each subsequent build will
have a higher number.
type: number
build_snapshot:
description: Whether this build is a snapshot build.
type: boolean
number:
description: A semantic version number.
type: string
required:
- number
- build_hash
- build_number
- build_snapshot
- build_flavor
- build_date
type: object
required:
- name
- uuid
- version
- status
- metrics
type: object
examples:
Connectors_create_email_connector_request:
summary: Create an email connector.
@ -9304,3 +9633,6 @@ x-tagGroups:
- name: SLOs
tags:
- slo
- name: Kibana HTTP APIs
tags:
- system

332
oas_docs/output/kibana.yaml
View file

@ -55,6 +55,7 @@ servers:
default: localhost:5601
- url: http://localhost:5601
description: local
- url: http://localhost:5622
tags:
- name: APM agent keys
description: >
@ -86,6 +87,8 @@ tags:
- name: slo
description: SLO APIs enable you to define, manage and track service-level objectives
x-displayName: slo
- name: system
x-displayName: system
paths:
/api/apm/agent_keys:
post:
@ -4034,6 +4037,58 @@ paths:
security:
- SLOs_basicAuth: []
- SLOs_apiKeyAuth: []
/api/status:
get:
operationId: /api/status#0
parameters:
- description: The version of the API to use
in: header
name: elastic-api-version
schema:
default: '2023-10-31'
enum:
- '2023-10-31'
type: string
- description: Set to "true" to get the response in v7 format.
in: query
name: v7format
required: false
schema:
type: boolean
- description: Set to "true" to get the response in v8 format.
in: query
name: v8format
required: false
schema:
type: boolean
responses:
'200':
content:
application/json; Elastic-Api-Version=2023-10-31:
schema:
anyOf:
- $ref: '#/components/schemas/Kibana_HTTP_APIs_core_status_response'
- $ref: >-
#/components/schemas/Kibana_HTTP_APIs_core_status_redactedResponse
description: >-
Kibana's operational status. A minimal response is sent for
unauthorized users.
'503':
content:
application/json; Elastic-Api-Version=2023-10-31:
schema:
anyOf:
- $ref: '#/components/schemas/Kibana_HTTP_APIs_core_status_response'
- $ref: >-
#/components/schemas/Kibana_HTTP_APIs_core_status_redactedResponse
description: >-
Kibana's operational status. A minimal response is sent for
unauthorized users.
summary: Get Kibana's current status
tags:
- system
security:
- Kibana_HTTP_APIs_basicAuth: []
components:
securitySchemes:
Connectors_basicAuth:
@ -4078,6 +4133,13 @@ components:
in: header
name: Authorization
description: 'e.g. Authorization: ApiKey base64AccessApiKey'
Kibana_HTTP_APIs_apiKeyAuth:
in: header
name: Authorization
type: apiKey
Kibana_HTTP_APIs_basicAuth:
scheme: basic
type: http
parameters:
Connectors_kbn_xsrf:
schema:
@ -9865,6 +9927,273 @@ components:
description: The SLO instance identifier
type: string
example: 8853df00-ae2e-11ed-90af-09bb6422b258
Kibana_HTTP_APIs_core_status_redactedResponse:
additionalProperties: false
description: A minimal representation of Kibana's operational status.
properties:
status:
additionalProperties: false
properties:
overall:
additionalProperties: false
properties:
level:
description: Service status levels as human and machine readable values.
enum:
- available
- degraded
- unavailable
- critical
type: string
required:
- level
type: object
required:
- overall
type: object
required:
- status
type: object
Kibana_HTTP_APIs_core_status_response:
additionalProperties: false
description: >-
Kibana's operational status as well as a detailed breakdown of plugin
statuses indication of various loads (like event loop utilization and
network traffic) at time of request.
properties:
metrics:
additionalProperties: false
description: Metric groups collected by Kibana.
properties:
collection_interval_in_millis:
description: The interval at which metrics should be collected.
type: number
elasticsearch_client:
additionalProperties: false
description: Current network metrics of Kibana's Elasticsearch client.
properties:
totalActiveSockets:
description: Count of network sockets currently in use.
type: number
totalIdleSockets:
description: Count of network sockets currently idle.
type: number
totalQueuedRequests:
description: Count of requests not yet assigned to sockets.
type: number
required:
- totalActiveSockets
- totalIdleSockets
- totalQueuedRequests
type: object
last_updated:
description: The time metrics were collected.
type: string
required:
- elasticsearch_client
- last_updated
- collection_interval_in_millis
type: object
name:
description: Kibana instance name.
type: string
status:
additionalProperties: false
properties:
core:
additionalProperties: false
description: Statuses of core Kibana services.
properties:
elasticsearch:
additionalProperties: false
properties:
detail:
description: Human readable detail of the service status.
type: string
documentationUrl:
description: A URL to further documentation regarding this service.
type: string
level:
description: >-
Service status levels as human and machine readable
values.
enum:
- available
- degraded
- unavailable
- critical
type: string
meta:
additionalProperties: {}
description: >-
An unstructured set of extra metadata about this
service.
type: object
summary:
description: A human readable summary of the service status.
type: string
required:
- level
- summary
- meta
type: object
savedObjects:
additionalProperties: false
properties:
detail:
description: Human readable detail of the service status.
type: string
documentationUrl:
description: A URL to further documentation regarding this service.
type: string
level:
description: >-
Service status levels as human and machine readable
values.
enum:
- available
- degraded
- unavailable
- critical
type: string
meta:
additionalProperties: {}
description: >-
An unstructured set of extra metadata about this
service.
type: object
summary:
description: A human readable summary of the service status.
type: string
required:
- level
- summary
- meta
type: object
required:
- elasticsearch
- savedObjects
type: object
overall:
additionalProperties: false
properties:
detail:
description: Human readable detail of the service status.
type: string
documentationUrl:
description: A URL to further documentation regarding this service.
type: string
level:
description: Service status levels as human and machine readable values.
enum:
- available
- degraded
- unavailable
- critical
type: string
meta:
additionalProperties: {}
description: An unstructured set of extra metadata about this service.
type: object
summary:
description: A human readable summary of the service status.
type: string
required:
- level
- summary
- meta
type: object
plugins:
additionalProperties:
additionalProperties: false
properties:
detail:
description: Human readable detail of the service status.
type: string
documentationUrl:
description: A URL to further documentation regarding this service.
type: string
level:
description: >-
Service status levels as human and machine readable
values.
enum:
- available
- degraded
- unavailable
- critical
type: string
meta:
additionalProperties: {}
description: An unstructured set of extra metadata about this service.
type: object
summary:
description: A human readable summary of the service status.
type: string
required:
- level
- summary
- meta
type: object
description: A dynamic mapping of plugin ID to plugin status.
type: object
required:
- overall
- core
- plugins
type: object
uuid:
description: >-
Unique, generated Kibana instance UUID. This UUID should persist
even if the Kibana process restarts.
type: string
version:
additionalProperties: false
properties:
build_date:
description: The date and time of this build.
type: string
build_flavor:
description: >-
The build flavour determines configuration and behavior of
Kibana. On premise users will almost always run the
"traditional" flavour, while other flavours are reserved for
Elastic-specific use cases.
enum:
- serverless
- traditional
type: string
build_hash:
description: >-
A unique hash value representing the git commit of this Kibana
build.
type: string
build_number:
description: >-
A monotonically increasing number, each subsequent build will
have a higher number.
type: number
build_snapshot:
description: Whether this build is a snapshot build.
type: boolean
number:
description: A semantic version number.
type: string
required:
- number
- build_hash
- build_number
- build_snapshot
- build_flavor
- build_date
type: object
required:
- name
- uuid
- version
- status
- metrics
type: object
examples:
Connectors_create_email_connector_request:
summary: Create an email connector.
@ -12056,3 +12385,6 @@ x-tagGroups:
- name: SLOs
tags:
- slo
- name: Kibana HTTP APIs
tags:
- system

17
oas_docs/overlays/kibana.overlays.yaml
View file

@ -14,20 +14,3 @@ actions:
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

2
packages/core/status/core-status-server-internal/src/routes/status.ts
View file

@ -86,7 +86,7 @@ export const registerStatusRoute = ({
// The `api` tag ensures that unauthenticated calls receive a 401 rather than a 302 redirect to login page.
// The `security:acceptJWT` tag allows route to be accessed with JWT credentials. It points to
// ROUTE_TAG_ACCEPT_JWT from '@kbn/security-plugin/server' that cannot be imported here directly.
tags: ['api', 'security:acceptJWT'],
tags: ['api', 'security:acceptJWT', 'oas-tag:system'],
access: 'public', // needs to be public to allow access from "system" users like k8s readiness probes.
summary: `Get Kibana's current status`,
},