[OAS] Add data views openAPI folder and first entrypoints

docs/api/data-views/create.asciidoc

@@ -6,6 +6,11 @@
 
 experimental[] Create data views.
 
+[NOTE]
+====
+For the most up-to-date API details, refer to the
+{kib-repo}/tree/{branch}/src/plugins/data_views/docs/openapi[open API specification].
+====
 
 [[data-views-api-create-request]]
 ==== Request

docs/api/data-views/default-get.asciidoc

@@ -6,6 +6,11 @@
 
 experimental[] Retrieve a default data view ID. Kibana UI uses the default data view unless user picks a different one.
 
+[NOTE]
+====
+For the most up-to-date API details, refer to the
+{kib-repo}/tree/{branch}/src/plugins/data_views/docs/openapi[open API specification].
+====
 
 [[data-views-api-default-get-request]]
 ==== Request

docs/api/data-views/default-set.asciidoc

@@ -7,6 +7,11 @@
 experimental[] Set a default data view ID. Kibana UI will use the default data view unless user picks a different one. 
 The API doesn't validate if given `data_view_id` is a valid id. 
 
+[NOTE]
+====
+For the most up-to-date API details, refer to the
+{kib-repo}/tree/{branch}/src/plugins/data_views/docs/openapi[open API specification].
+====
 
 [[data-views-api-default-set-request]]
 ==== Request

docs/api/data-views/delete.asciidoc

@@ -8,6 +8,11 @@ experimental[] Delete data views.
 
 WARNING: Once you delete a data view, _it cannot be recovered_.
 
+[NOTE]
+====
+For the most up-to-date API details, refer to the
+{kib-repo}/tree/{branch}/src/plugins/data_views/docs/openapi[open API specification].
+====
 
 [[data-views-api-delete-request]]
 ==== Request

docs/api/data-views/get-all.asciidoc

@@ -6,6 +6,12 @@
 
 experimental[] Retrieve a list of all data views.
 
+[NOTE]
+====
+For the most up-to-date API details, refer to the
+{kib-repo}/tree/{branch}/src/plugins/data_views/docs/openapi[open API specification].
+====
+
 
 [[data-views-api-get-all-request]]
 ==== Request

docs/api/data-views/get.asciidoc

@@ -6,6 +6,11 @@
 
 experimental[] Retrieve a single data view by ID.
 
+[NOTE]
+====
+For the most up-to-date API details, refer to the
+{kib-repo}/tree/{branch}/src/plugins/data_views/docs/openapi[open API specification].
+====
 
 [[data-views-api-get-request]]
 ==== Request

docs/api/data-views/runtime-fields/get.asciidoc

@@ -6,6 +6,11 @@
 
 experimental[] Get a runtime field
 
+[NOTE]
+====
+For the most up-to-date API details, refer to the
+{kib-repo}/tree/{branch}/src/plugins/data_views/docs/openapi[open API specification].
+====
 
 [[data-views-runtime-field-get-request]]
 ==== Request

docs/api/data-views/update.asciidoc

@@ -7,6 +7,11 @@
 experimental[] Update part of an data view. Only the specified fields are updated in the
 data view. Unspecified fields stay as they are persisted.
 
+[NOTE]
+====
+For the most up-to-date API details, refer to the
+{kib-repo}/tree/{branch}/src/plugins/data_views/docs/openapi[open API specification].
+====
 
 [[data-views-api-update-request]]
 ==== Request

src/plugins/data_views/docs/openapi/README.md

@@ -0,0 +1,35 @@
+# OpenAPI (Experimental)
+
+The current self-contained spec file is available as `bundled.json` or `bundled.yaml` and can be used for online tools like those found at <https://openapi.tools/>.
+This spec is experimental and may be incomplete or change later.
+
+A guide about the openApi specification can be found at [https://swagger.io/docs/specification/about/](https://swagger.io/docs/specification/about/).
+
+
+## The `openapi` folder
+
+* `entrypoint.yaml` is the overview file which pulls together all the paths and components.
+* [Paths](paths/README.md): Defines each endpoint.  A path can have one operation per http method.
+* [Components](components/README.md): Defines reusable components.
+
+## Tools
+
+It is possible to validate the docs before bundling them with the following
+command:
+
+```bash
+npx swagger-cli validate entrypoint.yaml
+```
+
+Then you can generate the `bundled` files by running the following commands:
+
+```bash
+npx @redocly/cli bundle entrypoint.yaml --output bundled.yaml --ext yaml
+npx @redocly/cli bundle entrypoint.yaml --output bundled.json --ext json
+```
+
+After generating the json bundle ensure that it is also valid by running the following command:
+
+```bash
+npx @redocly/cli lint bundled.json
+```