From 26aec8ce945cf5799731d30c998fc6fc31fc1245 Mon Sep 17 00:00:00 2001
From: Jacques Verre <jverre@gmail.com>
Date: Fri, 27 Sep 2024 17:18:22 +0100
Subject: [PATCH] Update openapi template

---
 .../src/main/resources/openapi_template.yml   | 40 ++++++++++++++-----
 1 file changed, 29 insertions(+), 11 deletions(-)

diff --git a/apps/opik-backend/src/main/resources/openapi_template.yml b/apps/opik-backend/src/main/resources/openapi_template.yml
index 91d611ed1b..62a2a981cb 100644
--- a/apps/opik-backend/src/main/resources/openapi_template.yml
+++ b/apps/opik-backend/src/main/resources/openapi_template.yml
@@ -1,20 +1,38 @@
 openapi: 3.1.0
 info :
-  description : "APIs"
+  description : |
+    The Opik REST API is currently in beta and subject to change. If you have any questions or feedback about the APIs, please reach out on GitHub: https://github.com/comet-ml/opik.
+
+    All of the methods listed in this documentation are used by either the SDK or the UI to interact with the Opik server. As a result,
+    the methods have been optimized for these use-cases in mind. If you are looking for a method that is not listed above, please create
+    and issue on GitHub or raise a PR!
+
+    Opik includes two main deployment options that results in slightly different API usage:
+
+    - **Self-hosted Opik instance:** You will simply need to specify the URL as `http://localhost:5173/api/<endpoint_path>` or similar. This is the default option for the docs.
+    - **Opik Cloud:** You will need to specify the Opik API Key and Opik Workspace in the header. The format of the header should be:
+
+      ```
+      {
+        "Comet-Workspace": "your-workspace-name",
+        "authorization": "your-api-key"
+      }
+      ```
+
+      Do take note here that the authorization header value does not include the `Bearer ` prefix. To switch to using the Opik Cloud in the documentation, you can
+      click on the edit button displayed when hovering over the `Base URL` displayed on the right hand side of the docs.
+
   version : "1.0.0"
-  title : "APIs"
+  title : "Opik REST API"
   contact :
-    name : "Support"
-    email : "support@comet.com"
+    name : "Github Repository"
+    url : "https://github.com/comet-ml/opik"
   license :
     name : "Apache 2.0"
     url : "http://www.apache.org/licenses/LICENSE-2.0.html"
 
 servers :
-  - url : "{basePath}/{apiVersion}"
-    description : "Local server"
-    variables:
-      basePath:
-        default: "http://localhost:8080"
-      apiVersion:
-        default: "v1"
\ No newline at end of file
+  - url: http://localhost:5173/api
+    description: Local server
+  - url: https://www.comet.com/opik/api
+    description: Opik Cloud