[Proposal] OpenAPI specifications for dashboards APIs about opensearch-dashboards

[seraphjiang]

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

• Could we list all existing saved object api so we could track progress
• could we have use one api to create an example

[ashwin-pc]

@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]

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]

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

[ashwin-pc]

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]

let's add sub tasks

• add example for creating visualization through saved object
• add example for creating dashboards through saved object
• add support build-in saved object type [viz, dashboards, index-pattern, datasource, workspace]
• add example for advanced settings