-
Notifications
You must be signed in to change notification settings - Fork 8.3k
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.
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
[OAS] Add saved objects openAPI folder #162522
Merged
Merged
Changes from all commits
Commits
Show all changes
11 commits
Select commit
Hold shift + click to select a range
db6ba5b
[OAS] Add saved objects openAPI folder
lcawl 0432a4a
Update readmes
lcawl 9dc48c6
[OAS] Add request and response examples
lcawl 56ca871
[OAS] Add import saved objects endpoint
lcawl be10b7e
[OAS] Add export objects API response example
lcawl 3b73f79
Merge branch 'main' into saved-objects-oas1
lcawl 9a9a126
[DOCS] Add note to API docs
lcawl 535c566
Merge branch 'main' into saved-objects-oas1
lcawl 68e4976
[OAS] Fix tags
lcawl aa9d68e
Clarify readme
lcawl fa1741a
Merge branch 'main' into saved-objects-oas1
lcawl File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| # OpenAPI (Experimental) | ||
|
|
||
| The current self-contained spec file is `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. | ||
|
|
||
| A guide about the openApi specification can be found at [https://swagger.io/docs/specification/about/](https://swagger.io/docs/specification/about/). | ||
|
|
||
| ## The `openapi` folder | ||
|
|
||
| * `entrypoint.yaml` is the overview file which pulls together all the paths and components. | ||
| * [Paths](paths/README.md): this defines each endpoint. A path can have one operation per http method. | ||
|
|
||
| ## Tools | ||
|
|
||
| To validate and bundle the docs, you can use [Redocly](https://redocly.com/docs/cli/) and [Swagger/OpenAPI CLI](https://www.npmjs.com/package/swagger-cli). | ||
|
|
||
| For example, run the following commands from the `packages/core/saved-objects/docs/openapi/` folder: | ||
|
|
||
| ```bash | ||
| npx swagger-cli validate entrypoint.yaml | ||
| ``` | ||
|
|
||
| Then you can 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 | ||
| ``` | ||
|
|
||
| After generating the json bundle ensure that it is also valid by running the following command: | ||
|
|
||
| ```bash | ||
| npx @redocly/cli lint bundled.json | ||
| ``` | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,326 @@ | ||
| { | ||
| "openapi": "3.1.0", | ||
| "info": { | ||
| "title": "Saved objects", | ||
| "description": "OpenAPI schema for saved object endpoints", | ||
| "version": "0.1", | ||
| "contact": { | ||
| "name": "Kibana Core Team" | ||
| }, | ||
| "license": { | ||
| "name": "Elastic License 2.0", | ||
| "url": "https://www.elastic.co/licensing/elastic-license" | ||
| } | ||
| }, | ||
| "servers": [ | ||
| { | ||
| "url": "http://localhost:5601", | ||
| "description": "local" | ||
| } | ||
| ], | ||
| "security": [ | ||
| { | ||
| "basicAuth": [] | ||
| }, | ||
| { | ||
| "apiKeyAuth": [] | ||
| } | ||
| ], | ||
| "tags": [ | ||
| { | ||
| "name": "saved objects", | ||
| "description": "Manage Kibana saved objects, including dashboards, visualizations, and more." | ||
| } | ||
| ], | ||
| "paths": { | ||
| "/api/saved_objects/_export": { | ||
| "post": { | ||
| "summary": "Retrieve sets of saved objects that you want to import into Kibana.", | ||
| "operationId": "exportSavedObjects", | ||
| "description": "This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. NOTE: The `savedObjects.maxImportExportSize` configuration setting limits the number of saved objects which may be exported.\n", | ||
| "tags": [ | ||
| "saved objects" | ||
| ], | ||
| "parameters": [ | ||
| { | ||
| "$ref": "#/components/parameters/kbn_xsrf" | ||
| } | ||
| ], | ||
| "requestBody": { | ||
| "required": true, | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "type": "object", | ||
| "anyOf": [ | ||
| { | ||
| "required": [ | ||
| "type" | ||
| ] | ||
| }, | ||
| { | ||
| "required": [ | ||
| "objects" | ||
| ] | ||
| } | ||
| ], | ||
| "properties": { | ||
| "excludeExportDetails": { | ||
| "description": "Do not add export details entry at the end of the stream.", | ||
| "type": "boolean", | ||
| "default": false | ||
| }, | ||
| "includeReferencesDeep": { | ||
| "description": "Includes all of the referenced objects in the exported objects.", | ||
| "type": "boolean" | ||
| }, | ||
| "objects": { | ||
| "description": "A list of objects to export.", | ||
| "type": "array", | ||
| "items": { | ||
| "type": "object" | ||
| } | ||
| }, | ||
| "type": { | ||
| "description": "The saved object types to include in the export.", | ||
| "oneOf": [ | ||
| { | ||
| "type": "string" | ||
| }, | ||
| { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "string" | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| }, | ||
| "examples": { | ||
| "exportSavedObjectsRequest": { | ||
| "$ref": "#/components/examples/export_objects_request" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "responses": { | ||
| "200": { | ||
| "description": "Indicates a successful call.", | ||
| "content": { | ||
| "multipart/form-data": { | ||
| "schema": { | ||
| "type": "string" | ||
| }, | ||
| "examples": { | ||
| "exportSavedObjectsResponse": { | ||
| "$ref": "#/components/examples/export_objects_response" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "400": { | ||
| "description": "Bad request.", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "type": "object", | ||
| "additionalProperties": true | ||
| } | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "servers": [ | ||
| { | ||
| "url": "https://localhost:5601" | ||
| } | ||
| ] | ||
| }, | ||
| "servers": [ | ||
| { | ||
| "url": "https://localhost:5601" | ||
| } | ||
| ] | ||
| }, | ||
| "/api/saved_objects/_import": { | ||
| "post": { | ||
| "summary": "Create sets of Kibana saved objects from a file created by the export API.", | ||
| "operationId": "importSavedObjects", | ||
| "description": "This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Saved objects can be imported only into the same version, a newer minor on the same major, or the next major. Exported saved objects are not backwards compatible and cannot be imported into an older version of Kibana.\n", | ||
| "tags": [ | ||
| "saved objects" | ||
| ], | ||
| "parameters": [ | ||
| { | ||
| "$ref": "#/components/parameters/kbn_xsrf" | ||
| }, | ||
| { | ||
| "in": "query", | ||
| "name": "compatibilityMode", | ||
| "schema": { | ||
| "type": "boolean" | ||
| }, | ||
| "required": false, | ||
| "description": "Applies various adjustments to the saved objects that are being imported to maintain compatibility between different Kibana versions. Use this option only if you encounter issues with imported saved objects. NOTE: This option cannot be used with the `createNewCopies` option.\n" | ||
| }, | ||
| { | ||
| "in": "query", | ||
| "name": "createNewCopies", | ||
| "schema": { | ||
| "type": "boolean" | ||
| }, | ||
| "required": false, | ||
| "description": "Creates copies of saved objects, regenerates each object ID, and resets the origin. When used, potential conflict errors are avoided. NOTE: This option cannot be used with the `overwrite` and `compatibilityMode` options.\n" | ||
| }, | ||
| { | ||
| "in": "query", | ||
| "name": "overwrite", | ||
| "schema": { | ||
| "type": "boolean" | ||
| }, | ||
| "required": false, | ||
| "description": "Overwrites saved objects when they already exist. When used, potential conflict errors are automatically resolved by overwriting the destination object. NOTE: This option cannot be used with the `createNewCopies` option.\n" | ||
| } | ||
| ], | ||
| "requestBody": { | ||
| "required": true, | ||
| "content": { | ||
| "multipart/form-data": { | ||
| "schema": { | ||
| "type": "object", | ||
| "description": "A file exported using the export API. NOTE: The `savedObjects.maxImportExportSize` configuration setting limits the number of saved objects which may be included in this file. Similarly, the `savedObjects.maxImportPayloadBytes` setting limits the overall size of the file that can be imported.\n" | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "responses": { | ||
| "200": { | ||
| "description": "Indicates a successful call.", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "type": "object", | ||
| "properties": { | ||
| "errors": { | ||
| "type": "array", | ||
| "description": "Indicates the import was unsuccessful and specifies the objects that failed to import. One object may result in multiple errors, which requires separate steps to resolve. For instance, a `missing_references` error and conflict error.\n" | ||
| }, | ||
| "success": { | ||
| "type": "boolean", | ||
| "description": "Indicates when the import was successfully completed. When set to false, some objects may not have been created. For additional information, refer to the `errors` and `successResults` properties.\n" | ||
| }, | ||
| "successCount": { | ||
| "type": "integer", | ||
| "description": "Indicates the number of successfully imported records." | ||
| }, | ||
| "successResults": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "object" | ||
| }, | ||
| "description": "Indicates the objects that are successfully imported, with any metadata if applicable. Objects are created only when all resolvable errors are addressed, including conflicts and missing references. If objects are created as new copies, each entry in the `successResults` array includes a `destinationId` attribute.\n" | ||
| }, | ||
| "warnings": { | ||
| "type": "array" | ||
| } | ||
| } | ||
| }, | ||
| "examples": { | ||
| "importObjectsResponse": { | ||
| "$ref": "#/components/examples/import_objects_response" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "400": { | ||
| "description": "Bad request.", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "type": "object", | ||
| "additionalProperties": true | ||
| } | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "servers": [ | ||
| { | ||
| "url": "https://localhost:5601" | ||
| } | ||
| ] | ||
| }, | ||
| "servers": [ | ||
| { | ||
| "url": "https://localhost:5601" | ||
| } | ||
| ] | ||
| } | ||
| }, | ||
| "components": { | ||
| "securitySchemes": { | ||
| "basicAuth": { | ||
| "type": "http", | ||
| "scheme": "basic" | ||
| }, | ||
| "apiKeyAuth": { | ||
| "type": "apiKey", | ||
| "in": "header", | ||
| "name": "ApiKey" | ||
| } | ||
| }, | ||
| "parameters": { | ||
| "kbn_xsrf": { | ||
| "schema": { | ||
| "type": "string" | ||
| }, | ||
| "in": "header", | ||
| "name": "kbn-xsrf", | ||
| "description": "Cross-site request forgery protection", | ||
| "required": true | ||
| } | ||
| }, | ||
| "examples": { | ||
| "export_objects_request": { | ||
| "summary": "Export a specific saved object.", | ||
| "value": { | ||
| "objects": [ | ||
| { | ||
| "type": "index-pattern", | ||
| "id": "90943e30-9a47-11e8-b64d-95841ca0b247" | ||
| } | ||
| ], | ||
| "includeReferencesDeep": false | ||
| } | ||
| }, | ||
| "export_objects_response": { | ||
| "summary": "The export objects API response contains a JSON record for each exported object and an export result details record.", | ||
| "value": "{\"attributes\":{\"fieldFormatMap\":\"{\\\"hour_of_day\\\":{}}\",\"name\":\"Kibana Sample Data Logs\",\"runtimeFieldMap\":\"{\\\"hour_of_day\\\":{\\\"type\\\":\\\"long\\\",\\\"script\\\":{\\\"source\\\":\\\"emit(doc['timestamp'].value.getHour());\\\"}}}\",\"timeFieldName\":\"timestamp\",\"title\":\"kibana_sample_data_logs\"},\"coreMigrationVersion\":\"8.8.0\",\"created_at\":\"2023-07-25T19:36:36.695Z\",\"id\":\"90943e30-9a47-11e8-b64d-95841ca0b247\",\"managed\":false,\"references\":[],\"type\":\"index-pattern\",\"typeMigrationVersion\":\"8.0.0\",\"updated_at\":\"2023-07-25T19:36:36.695Z\",\"version\":\"WzM5LDJd\"}\n{\"excludedObjects\":[],\"excludedObjectsCount\":0,\"exportedCount\":1,\"missingRefCount\":0,\"missingReferences\":[]}\n" | ||
| }, | ||
| "import_objects_response": { | ||
| "summary": "The import objects API response indicates a successful import and the objects are created. Since these objects are created as new copies, each entry in the successResults array includes a destinationId attribute.", | ||
| "value": { | ||
| "successCount": 1, | ||
| "success": true, | ||
| "warnings": [], | ||
| "successResults": [ | ||
| { | ||
| "type": "index-pattern", | ||
| "id": "90943e30-9a47-11e8-b64d-95841ca0b247", | ||
| "meta": { | ||
| "title": "Kibana Sample Data Logs", | ||
| "icon": "indexPatternApp" | ||
| }, | ||
| "managed": false, | ||
| "destinationId": "82d2760c-468f-49cf-83aa-b9a35b6a8943" | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
AFAIK, every api that has an openApi spec will have a
README. That's a lot of duplication and adds to the bundle size. The original intent of moving kibana to packages was to keep Kibana small (codes size wise) and fast.For now, it's probably ok but we need to watch that. @elastic/kibana-operations are we at all concerned about bundle size increasing?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agreed, if there are any space savings that can occur that's worth doing. Once we get to the point where the specs are being generated from the code there will hopefully be a lot less overhead too.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We can keep an eye on it, thanks for the heads up. We're removing most documentation from the distribution currently, unless it's referenced in kibana itself.