From 2c1cb7337faf6473195812c9a4f15c72035b18a7 Mon Sep 17 00:00:00 2001 From: Lu Yu Date: Wed, 15 May 2024 17:43:58 +0000 Subject: [PATCH 1/3] add openapi doc Signed-off-by: Lu Yu --- docs/index.html | 21 +++ docs/openapi/README.md | 0 docs/openapi/saved_objects/index.html | 30 +++++ docs/openapi/saved_objects/saved_objects.yml | 130 +++++++++++++++++++ 4 files changed, 181 insertions(+) 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/docs/index.html b/docs/index.html index ba48d8328604..ca940162d544 100644 --- a/docs/index.html +++ b/docs/index.html @@ -10,6 +10,7 @@ +
@@ -31,9 +32,29 @@ }, } + + + diff --git a/docs/openapi/README.md b/docs/openapi/README.md new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/docs/openapi/saved_objects/index.html b/docs/openapi/saved_objects/index.html new file mode 100644 index 000000000000..e5a1ef9d15ce --- /dev/null +++ b/docs/openapi/saved_objects/index.html @@ -0,0 +1,30 @@ + + + + + + + + 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 From 3992f4cf617113f8c84760a96902baea15977342 Mon Sep 17 00:00:00 2001 From: Lu Yu Date: Wed, 15 May 2024 22:18:59 +0000 Subject: [PATCH 2/3] add readme Signed-off-by: Lu Yu --- docs/index.html | 21 --------------------- docs/openapi/README.md | 9 +++++++++ docs/openapi/saved_objects/index.html | 1 - 3 files changed, 9 insertions(+), 22 deletions(-) diff --git a/docs/index.html b/docs/index.html index ca940162d544..ba48d8328604 100644 --- a/docs/index.html +++ b/docs/index.html @@ -10,7 +10,6 @@ -
@@ -32,29 +31,9 @@ }, } - - - diff --git a/docs/openapi/README.md b/docs/openapi/README.md index e69de29bb2d1..a19b2a9a830a 100644 --- 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. \ No newline at end of file diff --git a/docs/openapi/saved_objects/index.html b/docs/openapi/saved_objects/index.html index e5a1ef9d15ce..023837592c4d 100644 --- a/docs/openapi/saved_objects/index.html +++ b/docs/openapi/saved_objects/index.html @@ -15,7 +15,6 @@