Epic: Syncing OAS with Kibana code part I #180056
Assignees
Comments
jloleysens
added
the
Team:Core
|
Pinging @elastic/kibana-core (Team:Core) |
This was referenced Apr 5, 2024
jloleysens
added a commit
that referenced
this issue
Apr 9, 2024
## Summary Introduces a set of meta fields that will be used to track metadata lost in how we currently use `joi` inside of `@kbn/config-schema`. ## Notes * Related #180056 * Changes cherry-picked from #156357 * Changes are not used for anything in this PR, they are intended to enable our OAS generation scripts
jloleysens
added a commit
that referenced
this issue
Apr 11, 2024
rayafratkina
changed the title
MilestoneTeams can start providing response schemas and testing the OAS generated from We have added:
|
jloleysens
added a commit
that referenced
this issue
May 2, 2024
## Summary Related to #180056 Adds the ability to specify a content type for the request / response of an API. The current approach is to use the `options.accepts` value already present on the route but to also add the ability to specify a content type per response, otherwise fallback to `application/json`. ## Notes * Fixed an issue where we might not be iterating over response codes correctly (and updated test cases) * Refactored the `generate_oas.ts` script to be more maintainable (apologies for the noise)
jloleysens
changed the title
jloleysens
added a commit
that referenced
this issue
May 7, 2024
## Summary Part #180056. Adds new response schemas to the `/api/status` endpoint for the purposes of OAS generation. ## How to test 1. Start ES 2. Add `server.oas.enabled: true` to `kibana.dev.yml` 3. Start Kibana `yarn start --no-base-path` 4. `curl -s -uelastic:changeme http://localhost:5601/api/oas\?pathStartsWith\=/api/status | jq` <details> <summary>output</summary> ```json { "openapi": "3.0.0", "info": { "title": "Kibana HTTP APIs", "version": "0.0.0" }, "servers": [ { "url": "http://localhost:5601" } ], "paths": { "/api/status": { "get": { "summary": "Get Kibana's current status.", "responses": { "200": { "description": "Get Kibana's current status.", "content": { "application/json; Elastic-Api-Version=2023-10-31": { "schema": { "description": "Kibana's operational status. A minimal response is sent for unauthorized users.", "anyOf": [ { "$ref": "#/components/schemas/core.status.response" }, { "$ref": "#/components/schemas/core.status.redactedResponse" } ] } } } }, "503": { "description": "Get Kibana's current status.", "content": { "application/json; Elastic-Api-Version=2023-10-31": { "schema": { "description": "Kibana's operational status. A minimal response is sent for unauthorized users.", "anyOf": [ { "$ref": "#/components/schemas/core.status.response" }, { "$ref": "#/components/schemas/core.status.redactedResponse" } ] } } } } }, "parameters": [ { "in": "header", "name": "elastic-api-version", "description": "The version of the API to use", "schema": { "type": "string", "enum": [ "2023-10-31" ], "default": "2023-10-31" } }, { "name": "v7format", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Set to \"true\" to get the response in v7 format." }, { "name": "v8format", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Set to \"true\" to get the response in v8 format." } ], "operationId": "/api/status#0" } } }, "components": { "schemas": { "core.status.response": { "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.", "type": "object", "properties": { "name": { "description": "Kibana instance name.", "type": "string" }, "uuid": { "description": "Unique, generated Kibana instance UUID. This UUID should persist even if the Kibana process restarts.", "type": "string" }, "version": { "type": "object", "properties": { "number": { "description": "A semantic version number.", "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" }, "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.", "anyOf": [ { "enum": [ "serverless" ], "type": "string" }, { "enum": [ "traditional" ], "type": "string" } ] }, "build_date": { "description": "The date and time of this build.", "type": "string" } }, "additionalProperties": false, "required": [ "number", "build_hash", "build_number", "build_snapshot", "build_flavor", "build_date" ] }, "status": { "type": "object", "properties": { "overall": { "type": "object", "properties": { "level": { "description": "Service status levels as human and machine readable values.", "anyOf": [ { "enum": [ "available" ], "type": "string" }, { "enum": [ "degraded" ], "type": "string" }, { "enum": [ "unavailable" ], "type": "string" }, { "enum": [ "critical" ], "type": "string" } ] }, "summary": { "description": "A human readable summary of the service status.", "type": "string" }, "detail": { "description": "Human readable detail of the service status.", "type": "string" }, "documentationUrl": { "description": "A URL to further documentation regarding this service.", "type": "string" }, "meta": { "description": "An unstructured set of extra metadata about this service.", "type": "object", "additionalProperties": {} } }, "additionalProperties": false, "required": [ "level", "summary", "meta" ] }, "core": { "description": "Statuses of core Kibana services.", "type": "object", "properties": { "elasticsearch": { "type": "object", "properties": { "level": { "description": "Service status levels as human and machine readable values.", "anyOf": [ { "enum": [ "available" ], "type": "string" }, { "enum": [ "degraded" ], "type": "string" }, { "enum": [ "unavailable" ], "type": "string" }, { "enum": [ "critical" ], "type": "string" } ] }, "summary": { "description": "A human readable summary of the service status.", "type": "string" }, "detail": { "description": "Human readable detail of the service status.", "type": "string" }, "documentationUrl": { "description": "A URL to further documentation regarding this service.", "type": "string" }, "meta": { "description": "An unstructured set of extra metadata about this service.", "type": "object", "additionalProperties": {} } }, "additionalProperties": false, "required": [ "level", "summary", "meta" ] }, "savedObjects": { "type": "object", "properties": { "level": { "description": "Service status levels as human and machine readable values.", "anyOf": [ { "enum": [ "available" ], "type": "string" }, { "enum": [ "degraded" ], "type": "string" }, { "enum": [ "unavailable" ], "type": "string" }, { "enum": [ "critical" ], "type": "string" } ] }, "summary": { "description": "A human readable summary of the service status.", "type": "string" }, "detail": { "description": "Human readable detail of the service status.", "type": "string" }, "documentationUrl": { "description": "A URL to further documentation regarding this service.", "type": "string" }, "meta": { "description": "An unstructured set of extra metadata about this service.", "type": "object", "additionalProperties": {} } }, "additionalProperties": false, "required": [ "level", "summary", "meta" ] } }, "additionalProperties": false, "required": [ "elasticsearch", "savedObjects" ] }, "plugins": { "description": "A dynamic mapping of plugin ID to plugin status.", "type": "object", "additionalProperties": { "type": "object", "properties": { "level": { "description": "Service status levels as human and machine readable values.", "anyOf": [ { "enum": [ "available" ], "type": "string" }, { "enum": [ "degraded" ], "type": "string" }, { "enum": [ "unavailable" ], "type": "string" }, { "enum": [ "critical" ], "type": "string" } ] }, "summary": { "description": "A human readable summary of the service status.", "type": "string" }, "detail": { "description": "Human readable detail of the service status.", "type": "string" }, "documentationUrl": { "description": "A URL to further documentation regarding this service.", "type": "string" }, "meta": { "description": "An unstructured set of extra metadata about this service.", "type": "object", "additionalProperties": {} } }, "additionalProperties": false, "required": [ "level", "summary", "meta" ] } } }, "additionalProperties": false, "required": [ "overall", "core", "plugins" ] }, "metrics": { "description": "Metric groups collected by Kibana.", "type": "object", "properties": { "elasticsearch_client": { "description": "Current network metrics of Kibana's Elasticsearch client.", "type": "object", "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" } }, "additionalProperties": false, "required": [ "totalActiveSockets", "totalIdleSockets", "totalQueuedRequests" ] }, "last_updated": { "description": "The time metrics were collected.", "type": "string" }, "collection_interval_in_millis": { "description": "The interval at which metrics should be collected.", "type": "number" } }, "additionalProperties": false, "required": [ "elasticsearch_client", "last_updated", "collection_interval_in_millis" ] } }, "additionalProperties": false, "required": [ "name", "uuid", "version", "status", "metrics" ] }, "core.status.redactedResponse": { "description": "A minimal representation of Kibana's operational status.", "type": "object", "properties": { "status": { "type": "object", "properties": { "overall": { "type": "object", "properties": { "level": { "description": "Service status levels as human and machine readable values.", "anyOf": [ { "enum": [ "available" ], "type": "string" }, { "enum": [ "degraded" ], "type": "string" }, { "enum": [ "unavailable" ], "type": "string" }, { "enum": [ "critical" ], "type": "string" } ] } }, "additionalProperties": false, "required": [ "level" ] } }, "additionalProperties": false, "required": [ "overall" ] } }, "additionalProperties": false, "required": [ "status" ] } }, "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization" } } }, "security": [ { "basicAuth": [] } ] } ``` </details> Related to #181622 ## Notes * Tip from @lcawl : "If you want to see Bump previews of your files too, I’ve been doing it via the preview command per https://docs.bump.sh/help/continuous-integration/cli/#bump-preview-file"
This was referenced May 14, 2024
|
Related to #181240 is there a method to mark an entire endpoint as deprecated? e.g. there are some deprecated endpoints in alerting and cases. Could we add a "deprecated" option in https://github.com/elastic/kibana/blob/main/packages/core/http/core-http-server/src/router/route.ts? Created #186003 to track this request |
This was referenced May 22, 2024
This was referenced May 24, 2024
This was referenced Jun 6, 2024
|
FYI The Elasticsearch specifications now have a cool |
Nice @lcawl ! FMI, do you know where this value comes from? Is it something that is set in ES code (i.e., when the code gets merged?) I'm just thinking it might be tricky to establish this date for Kibana (and ES) APIs as they're released in different channels (on prem, cloud, serverless) so what would the "since" date be and does it make sense for it to be captured in the code? |
|
AFAIK it is something optionally added to the specification (which for Elasticsearch is maintained separately from the code) and is only applicable to on-prem per its description in https://github.com/elastic/elasticsearch-specification/blob/main/docs/add-new-api.md. I presume it's not necessary in serverless since we have version info in the headers. However in the on-prem scenario, I'm investigating whether this info in an |
|
I'm going to consider this first batch of enablement work done. There are a few remaining items that will live on as individual issues (ex. available since), but I believe the goal of enabling OAS generation from code has been achieved and enhancements/fixes/refinements remain. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Summary
We intend to use this issue to track progress of the work being done to enable Kibana's runtime validation schemas to generate OAS.
The approach
@kbn/config-schema. It is possible to support other runtime validation schemas, but to start with we will only support@kbn/config-schema.Tasks
Future tasks
experimentalAPIs #181995discriminator#181994The text was updated successfully, but these errors were encountered: