From 14ecd759accdfcace84724bec17d1c3c8778c72c Mon Sep 17 00:00:00 2001 From: Ashwin P Chandran Date: Tue, 14 May 2024 18:52:27 -0700 Subject: [PATCH 1/4] [OE] Adds dev doc script to precommit hook (#6585) * Adds doc generation to pre commit hook Signed-off-by: Ashwin P Chandran * Add check hook to pre commit Signed-off-by: Ashwin P Chandran * Changeset file for PR #6585 created/updated * Update error message Signed-off-by: Ashwin P Chandran * Improve error message Co-authored-by: Miki Signed-off-by: Ashwin P Chandran * fixes lint issue Signed-off-by: Ashwin P Chandran --------- Signed-off-by: Ashwin P Chandran Signed-off-by: Ashwin P Chandran Co-authored-by: opensearch-changeset-bot[bot] <154024398+opensearch-changeset-bot[bot]@users.noreply.github.com> Co-authored-by: Miki --- changelogs/fragments/6585.yml | 2 + scripts/precommit_hook.js | 1 + src/dev/precommit_hook/check_dev_docs.js | 18 ++++++++ .../precommit_hook/get_files_for_commit.js | 42 +++++++++++++------ src/dev/precommit_hook/index.js | 3 +- src/dev/run_precommit_hook.js | 15 ++++++- 6 files changed, 66 insertions(+), 15 deletions(-) create mode 100644 changelogs/fragments/6585.yml create mode 100644 src/dev/precommit_hook/check_dev_docs.js diff --git a/changelogs/fragments/6585.yml b/changelogs/fragments/6585.yml new file mode 100644 index 000000000000..311fa8da3abc --- /dev/null +++ b/changelogs/fragments/6585.yml @@ -0,0 +1,2 @@ +chore: +- Adds a git pre commit hook to ensure that developer docs are always updated ([#6585](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/6585)) \ No newline at end of file diff --git a/scripts/precommit_hook.js b/scripts/precommit_hook.js index 1d5485c64905..eb5347071386 100644 --- a/scripts/precommit_hook.js +++ b/scripts/precommit_hook.js @@ -29,4 +29,5 @@ */ require('@osd/optimizer').registerNodeAutoTranspilation(); +require('./generate_docs_sidebar'); require('../src/dev/run_precommit_hook'); diff --git a/src/dev/precommit_hook/check_dev_docs.js b/src/dev/precommit_hook/check_dev_docs.js new file mode 100644 index 000000000000..3a134dffb2b3 --- /dev/null +++ b/src/dev/precommit_hook/check_dev_docs.js @@ -0,0 +1,18 @@ +/* + * Copyright OpenSearch Contributors + * SPDX-License-Identifier: Apache-2.0 + */ + +const SIDEBAR_PATH = 'docs/_sidebar.md'; + +export async function checkDevDocs(log, files) { + files.map((file) => { + const path = file.getRelativePath(); + + if (path === SIDEBAR_PATH) { + throw Error( + `The ${SIDEBAR_PATH} file of the developer docs has been modified but is not ready to be committed. This can be done by performing "git add ${SIDEBAR_PATH}" and committing the changes.` + ); + } + }); +} diff --git a/src/dev/precommit_hook/get_files_for_commit.js b/src/dev/precommit_hook/get_files_for_commit.js index b0a18f650f70..7691df3c0fa7 100644 --- a/src/dev/precommit_hook/get_files_for_commit.js +++ b/src/dev/precommit_hook/get_files_for_commit.js @@ -34,20 +34,9 @@ import { fromNode as fcb } from 'bluebird'; import { REPO_ROOT } from '@osd/utils'; import { File } from '../file'; -/** - * Get the files that are staged for commit (excluding deleted files) - * as `File` objects that are aware of their commit status. - * - * @param {String} repoPath - * @return {Promise>} - */ -export async function getFilesForCommit() { - const simpleGit = new SimpleGit(REPO_ROOT); - - const output = await fcb((cb) => simpleGit.diff(['--name-status', '--cached'], cb)); - +function getFileList(diffText) { return ( - output + diffText .split('\n') // Ignore blank lines .filter((line) => line.trim().length > 0) @@ -69,3 +58,30 @@ export async function getFilesForCommit() { .filter(Boolean) ); } + +/** + * Get the files that are staged for commit (excluding deleted files) + * as `File` objects that are aware of their commit status. + * + * @return {Promise>} + */ +export async function getFilesForCommit() { + const simpleGit = new SimpleGit(REPO_ROOT); + + const staged = await fcb((cb) => simpleGit.diff(['--name-status', '--cached'], cb)); // staged + + return getFileList(staged); +} + +/** + * Get the unstaged files as `File` objects that are aware of their commit status. + * + * @return {Promise>} + */ +export async function getUnstagedFiles() { + const simpleGit = new SimpleGit(REPO_ROOT); + + const unstaged = await fcb((cb) => simpleGit.diff(['--name-status'], cb)); + + return getFileList(unstaged); +} diff --git a/src/dev/precommit_hook/index.js b/src/dev/precommit_hook/index.js index 14bf1af2a34b..898b4393d860 100644 --- a/src/dev/precommit_hook/index.js +++ b/src/dev/precommit_hook/index.js @@ -29,4 +29,5 @@ */ export { checkFileCasing } from './check_file_casing'; -export { getFilesForCommit } from './get_files_for_commit'; +export { getFilesForCommit, getUnstagedFiles } from './get_files_for_commit'; +export { checkDevDocs } from './check_dev_docs'; diff --git a/src/dev/run_precommit_hook.js b/src/dev/run_precommit_hook.js index 86a279166aca..b840fca99752 100644 --- a/src/dev/run_precommit_hook.js +++ b/src/dev/run_precommit_hook.js @@ -31,13 +31,26 @@ import { run, combineErrors } from '@osd/dev-utils'; import * as Eslint from './eslint'; import * as Stylelint from './stylelint'; -import { getFilesForCommit, checkFileCasing } from './precommit_hook'; +import { + getFilesForCommit, + getUnstagedFiles, + checkFileCasing, + checkDevDocs, +} from './precommit_hook'; run( async ({ log, flags }) => { const files = await getFilesForCommit(); + const unstagedFiles = await getUnstagedFiles(); const errors = []; + try { + // Check if the dev docs sidebar has been updated but not staged + await checkDevDocs(log, unstagedFiles); + } catch (error) { + errors.push(error); + } + try { await checkFileCasing(log, files); } catch (error) { From 22a88ae9707b79122368f2def667d1e3ba14ea5f Mon Sep 17 00:00:00 2001 From: Lu Yu Date: Tue, 14 May 2024 20:52:29 -0700 Subject: [PATCH 2/4] Move @BSFishy to emeritus maintainer (#6790) * Move @BSFishy to emeritus maintainer Signed-off-by: Lu Yu * Changeset file for PR #6790 created/updated --------- Signed-off-by: Lu Yu Co-authored-by: opensearch-changeset-bot[bot] <154024398+opensearch-changeset-bot[bot]@users.noreply.github.com> --- .github/CODEOWNERS | 2 +- MAINTAINERS.md | 2 +- changelogs/fragments/6790.yml | 2 ++ 3 files changed, 4 insertions(+), 2 deletions(-) create mode 100644 changelogs/fragments/6790.yml diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 88e62892d9a9..4cece3b8f608 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1 +1 @@ -* @ananzh @kavilla @AMoo-Miki @ashwin-pc @joshuarrrr @abbyhu2000 @zengyan-amazon @zhongnansu @manasvinibs @ZilongX @Flyingliuhub @BSFishy @curq @bandinib-amzn @SuZhou-Joe @ruanyl @BionIT @xinruiba @zhyuanqi +* @ananzh @kavilla @AMoo-Miki @ashwin-pc @joshuarrrr @abbyhu2000 @zengyan-amazon @zhongnansu @manasvinibs @ZilongX @Flyingliuhub @curq @bandinib-amzn @SuZhou-Joe @ruanyl @BionIT @xinruiba @zhyuanqi diff --git a/MAINTAINERS.md b/MAINTAINERS.md index d6155efcd837..fcd92f0eb239 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -17,7 +17,6 @@ This document contains a list of maintainers in this repo. See [opensearch-proje | Manasvini B Suryanarayana | [manasvinibs](https://github.com/manasvinibs) | Amazon | | Tao Liu | [Flyingliuhub](https://github.com/Flyingliuhub) | Amazon | | Zilong Xia | [ZilongX](https://github.com/ZilongX) | Amazon | -| Matt Provost | [BSFishy](https://github.com/BSFishy) | Amazon | | Sirazh Gabdullin | [curq](https://github.com/curq) | External contributor | | Bandini Bhopi | [bandinib-amzn](https://github.com/bandinib-amzn) | Amazon | | Su Zhou | [SuZhou-Joe](https://github.com/SuZhou-Joe) | Amazon | @@ -35,3 +34,4 @@ This document contains a list of maintainers in this repo. See [opensearch-proje | Bishoy Boktor | [boktorbb](https://github.com/boktorbb) | Amazon | | Sean Neumann | [seanneumann](https://github.com/seanneumann) | Contributor | | Kristen Tian | [kristenTian](https://github.com/kristenTian) | Amazon | +| Matt Provost | [BSFishy](https://github.com/BSFishy) | Amazon | diff --git a/changelogs/fragments/6790.yml b/changelogs/fragments/6790.yml new file mode 100644 index 000000000000..afd05b60c082 --- /dev/null +++ b/changelogs/fragments/6790.yml @@ -0,0 +1,2 @@ +doc: +- Move @BSFishy to emeritus maintainer ([#6790](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/6790)) \ No newline at end of file From 293e1a5c30bd996cc4329e265e4e085dc0b0c702 Mon Sep 17 00:00:00 2001 From: Lu Yu Date: Wed, 15 May 2024 15:33:32 -0700 Subject: [PATCH 3/4] add @mengweieric as maintainer (#6798) * add @mengweieric as maintainer Signed-off-by: Lu Yu * Changeset file for PR #6798 created/updated --------- Signed-off-by: Lu Yu Co-authored-by: opensearch-changeset-bot[bot] <154024398+opensearch-changeset-bot[bot]@users.noreply.github.com> --- .github/CODEOWNERS | 2 +- MAINTAINERS.md | 1 + changelogs/fragments/6798.yml | 2 ++ 3 files changed, 4 insertions(+), 1 deletion(-) create mode 100644 changelogs/fragments/6798.yml diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 4cece3b8f608..bf58f69e1c83 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1 +1 @@ -* @ananzh @kavilla @AMoo-Miki @ashwin-pc @joshuarrrr @abbyhu2000 @zengyan-amazon @zhongnansu @manasvinibs @ZilongX @Flyingliuhub @curq @bandinib-amzn @SuZhou-Joe @ruanyl @BionIT @xinruiba @zhyuanqi +* @ananzh @kavilla @AMoo-Miki @ashwin-pc @joshuarrrr @abbyhu2000 @zengyan-amazon @zhongnansu @manasvinibs @ZilongX @Flyingliuhub @curq @bandinib-amzn @SuZhou-Joe @ruanyl @BionIT @xinruiba @zhyuanqi @mengweieric diff --git a/MAINTAINERS.md b/MAINTAINERS.md index fcd92f0eb239..7f7dff5d37fe 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -24,6 +24,7 @@ This document contains a list of maintainers in this repo. See [opensearch-proje | Lu Yu | [BionIT](https://github.com/BionIT) | Amazon | | Xinrui Bai | [xinruiba](https://github.com/xinruiba) | Amazon | | Ella Zhu | [zhyuanqi](https://github.com/zhyuanqi) | Amazon | +| Eric Wei | [mengweieric](https://github.com/mengweieric) | Amazon | ## Emeritus diff --git a/changelogs/fragments/6798.yml b/changelogs/fragments/6798.yml new file mode 100644 index 000000000000..de03d466154b --- /dev/null +++ b/changelogs/fragments/6798.yml @@ -0,0 +1,2 @@ +doc: +- Add mengweieric as maintainer ([#6798](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/6798)) \ No newline at end of file From bd62a5dc00f47f1c47686ceb510e0a73e1870633 Mon Sep 17 00:00:00 2001 From: Lu Yu Date: Wed, 15 May 2024 16:58:51 -0700 Subject: [PATCH 4/4] Add OpenAPI specification for get and create saved object APIs (#6799) * add openapi doc Signed-off-by: Lu Yu * add readme Signed-off-by: Lu Yu * Changeset file for PR #6799 created/updated --------- Signed-off-by: Lu Yu 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