Skip to content
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.

Sign up for GitHub

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

[Backport 2.x] Add OpenAPI specification for get and create saved object APIs #6801

Merged
merged 1 commit into from
May 16, 2024
Merged

[Backport 2.x] Add OpenAPI specification for get and create saved object APIs #6801

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions changelogs/fragments/6799.yml
View file
Open in desktop
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))
9 changes: 9 additions & 0 deletions docs/openapi/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
29 changes: 29 additions & 0 deletions docs/openapi/saved_objects/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>
130 changes: 130 additions & 0 deletions docs/openapi/saved_objects/saved_objects.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Loading