search

opensearch-project / OpenSearch-Dashboards

📊 Open source visualization dashboards for OpenSearch.
https://opensearch.org/docs/latest/dashboards/index/
Apache License 2.0
1.67k stars 871 forks source link

[Proposal] OpenAPI specifications for dashboards APIs #6719

Open BionIT opened 5 months ago

BionIT commented 5 months ago

Overview

In the past few years, we have received many feedback from the community about the gap of documentation, the confusion in using our APIs. The proposal aims to come up with a solution to enable a standard way to define and document our APIs, starting with saved objects APIs which have been mentioned in several past discussions and not well documented.

Related discussions/issues: https://github.com/opensearch-project/OpenSearch-Dashboards/issues/1647 https://github.com/opensearch-project/documentation-website/issues/3799 https://github.com/opensearch-project/OpenSearch-Dashboards/issues/1700 https://github.com/opensearch-project/OpenSearch-Dashboards/issues/1723

Why 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.

The benefits that came out of the box and would help both developers and users of dashboards APIs.

Saved object API

Being the fundamental of OpenSearch Dashboards' functionality, Saved object APIs allows various operations (CRUDL) to manage the objects including dashboards, visualizations, saved searches, and more. However, without looking through the source code or poking around to find examples, it is pretty difficult for people to understand how the saved object API works. Using saved object as example would help reduce the gap as well as to demonstrate the benefits.

With more APIs being introduced to the dashboards, we can use the spec of saved object as example to ensure new APIs get documented following the same standards.

Goal

Dashboards have several APIs, and we propose to start with saved object APIs

Example

https://bionit.github.io/#/Saved%20Objects

Screenshot from 2024-05-08 15-24-04

seraphjiang commented 5 months ago

Thanks @BionIT , like the idea to use swagger to generate api doc

ashwin-pc commented 4 months ago

@BionIT Love the idea! Have you looked into the existing API doc generation tool? yarn docs:acceptApiChanges . This documents Plugin API's though but id like to have one consolidated tool rather than two if possible.

BionIT commented 4 months ago

Thanks @ashwin-pc! Yeah, I looked at it which using api-documenter behind the scene to generate markdowns, it is different from what I am proposing here which is to provide API specification which explains how our dashboard rest API behaves and what to expect from the API in a standard format. It can work together with swagger UI.

zengyan-amazon commented 4 months ago

Thanks @BionIT ! It is a great idea to leverage Swagger to improve the discovery and integrity of OpenSearch Dashboards APIs!

ashwin-pc commented 4 months ago

Makes sense. Will this be an automated flow or do we have to track it manually? Also is there a reason you are limiting it to just saved objects? Sicne we have some other useful API's like the stats API that could benefit from this :)

seraphjiang commented 4 months ago

let's add sub tasks