From 331c43677c5dab40a52511272d26edcd6e43e6d7 Mon Sep 17 00:00:00 2001 From: "opensearch-trigger-bot[bot]" <98922864+opensearch-trigger-bot[bot]@users.noreply.github.com> Date: Thu, 16 May 2024 13:49:22 -0700 Subject: [PATCH] Add OpenAPI specification for get and create saved object APIs (#6799) (#6801) * add openapi doc * add readme * Changeset file for PR #6799 created/updated --------- (cherry picked from commit bd62a5dc00f47f1c47686ceb510e0a73e1870633) Signed-off-by: Lu Yu Signed-off-by: github-actions[bot] Co-authored-by: github-actions[bot] Co-authored-by: opensearch-changeset-bot[bot] <154024398+opensearch-changeset-bot[bot]@users.noreply.github.com> --- changelogs/fragments/6799.yml | 2 + docs/openapi/README.md | 9 ++ docs/openapi/saved_objects/index.html | 29 +++++ docs/openapi/saved_objects/saved_objects.yml | 130 +++++++++++++++++++ 4 files changed, 170 insertions(+) create mode 100644 changelogs/fragments/6799.yml create mode 100644 docs/openapi/README.md create mode 100644 docs/openapi/saved_objects/index.html create mode 100644 docs/openapi/saved_objects/saved_objects.yml diff --git a/changelogs/fragments/6799.yml b/changelogs/fragments/6799.yml new file mode 100644 index 000000000000..0fc28064724d --- /dev/null +++ b/changelogs/fragments/6799.yml @@ -0,0 +1,2 @@ +doc: +- Add OpenAPI specification for GET and CREATE saved object API ([#6799](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/6799)) \ No newline at end of file diff --git a/docs/openapi/README.md b/docs/openapi/README.md new file mode 100644 index 000000000000..a19b2a9a830a --- /dev/null +++ b/docs/openapi/README.md @@ -0,0 +1,9 @@ +## OpenAPI Specification For OpenSearch Dashboards API + +### OpenAPI +The OpenAPI (https://swagger.io/specification/) Specification defines a standard, language-agnostic interface to the HTTP RESTful APIs which allows both humans and computers to discover and understand the functionalities provided by the service without having to read through the source code or lengthy documentation. When properly defined, a consumer of the API can understand and interact with the service with a minimal amount of efforts. The OpenAPI definition file can be in the YAML or JSON format. + +When generated, OpenAPI definition can then be used by documentation generation tools to display the API such as swagger UI, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases. + +### Starting Up the Swagger UI Locally +To start up the swagger UI locally for development or validation purposes, you can simply start a server in the directory where the index.html file is located. `npx serve` is a simple way to start a server. \ No newline at end of file diff --git a/docs/openapi/saved_objects/index.html b/docs/openapi/saved_objects/index.html new file mode 100644 index 000000000000..023837592c4d --- /dev/null +++ b/docs/openapi/saved_objects/index.html @@ -0,0 +1,29 @@ + + + + + + + + Saved Object API + + + +
+ + + + + + \ No newline at end of file diff --git a/docs/openapi/saved_objects/saved_objects.yml b/docs/openapi/saved_objects/saved_objects.yml new file mode 100644 index 000000000000..3d50114c2c2c --- /dev/null +++ b/docs/openapi/saved_objects/saved_objects.yml @@ -0,0 +1,130 @@ +openapi: 3.0.3 +info: + version: v1 + title: OpenSearch Dashboards Saved Objects API + contact: + name: OpenSearch Dashboards Team + description: |- + OpenAPI schema for OpenSearch Dashboards Saved Objects API +tags: + - name: saved objects + description: Manage Dashboards saved objects, including dashboards, visualizations, saved search, and more. +paths: + /api/saved_objects/{type}/{id}: + get: + tags: + - saved objects + summary: Retrieve a single saved object by type and id. + parameters: + - $ref: '#/components/parameters/id' + - $ref: '#/components/parameters/type' + responses: + '200': + description: The saved object is successfully retrieved. + content: + application/json: + schema: + type: object + '404': + description: The saved object does not exist. + content: + application/json: + schema: + type: object + post: + tags: + - saved objects + summary: Create a new saved object with type and id. + parameters: + - $ref: '#components/parameters/type' + - $ref: '#components/parameters/id' + - in: query + name: overwrite + description: If set to true, will overwrite the existing saved object with same type and id. + schema: + type: boolean + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - attributes + properties: + attributes: + type: object + description: The metadata of the saved object to be created, and the object is not validated. + migrationVersion: + type: object + description: The information about the migrations that have been applied to this saved object to be created. + references: + description: List of objects that describe other saved objects the created object references. + type: array + items: + type: object + properties: + id: + type: string + name: + type: string + type: + type: string + initialNamespaces: + description: Namespaces that this saved object exists in. This attribute is only used for multi-namespace saved object types. + type: array + items: + type: string + workspaces: + type: array + items: + type: string + description: Workspaces that this saved object exists in. + responses: + '200': + description: The creation request is successful + content: + application/json: + schema: + type: object + '400': + description: Bad request + content: + application/json: + schema: + $ref: '#/components/schemas/400_bad_request' +components: + parameters: + type: + name: type + in: path + description: The type of SavedObject to retrieve + required: true + schema: + type: string + id: + name: id + in: path + description: Unique id of the saved object. + required: true + schema: + type: string + schemas: + 400_bad_request: + title: Bad request + type: object + required: + - error + - message + - statusCode + properties: + error: + type: string + enum: + - Bad Request + message: + type: string + statusCode: + type: integer + enum: + - 400 \ No newline at end of file