Add OpenAPI specification for get and create saved object APIs (#6799)

* add openapi doc Signed-off-by: Lu Yu <[email protected]> * add readme Signed-off-by: Lu Yu <[email protected]> * Changeset file for PR #6799 created/updated --------- Signed-off-by: Lu Yu <[email protected]> Co-authored-by: opensearch-changeset-bot[bot] <154024398+opensearch-changeset-bot[bot]@users.noreply.github.com>
opensearch-project · May 15, 2024 · bd62a5d · bd62a5d
1 parent 293e1a5
commit bd62a5d
Show file tree

Hide file tree

Showing 4 changed files with 170 additions and 0 deletions.
diff --git a/changelogs/fragments/6799.yml 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))
diff --git a/docs/openapi/README.md 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. 
diff --git a/docs/openapi/saved_objects/index.html b/docs/openapi/saved_objects/index.html
@@ -0,0 +1,29 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="stylesheet" type="text/css" href="//unpkg.com/swagger-ui-dist@3/swagger-ui.css">
+
+  <title>Saved Object API</title>
+
+<body>
+
+  <div id="api-docs" />
+
+  <script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
+  <script>
+
+    window.onload = function() {
+      const ui = SwaggerUIBundle({
+        url: "saved_objects.yml",
+        dom_id: "#api-docs",
+        deepLinking: true,
+      })
+
+    }
+
+  </script>
+
+</body>
+</html>
diff --git a/docs/openapi/saved_objects/saved_objects.yml 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
Original file line number	Diff line number	Diff line change
		@@ -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))