From c7db8f81603d9af083b58d828b69dc3d953d7b3b Mon Sep 17 00:00:00 2001
From: Joakim Bygdell <joakim.bygdell@nbis.se>
Date: Mon, 24 Feb 2025 10:33:08 +0100
Subject: [PATCH] Update to match the demo from last Friday.

---
 sda/cmd/download/swagger_v1.yml | 49 +++++++++++++++++++++------------
 1 file changed, 32 insertions(+), 17 deletions(-)

diff --git a/sda/cmd/download/swagger_v1.yml b/sda/cmd/download/swagger_v1.yml
index 4b75ef468..aa4d791d4 100644
--- a/sda/cmd/download/swagger_v1.yml
+++ b/sda/cmd/download/swagger_v1.yml
@@ -2,13 +2,14 @@ openapi: 3.0.3
 info:
   title: SDA file download API
   version: "1.0"
+  description: This is the external data out API for the Sensitive Data Archive. Data is delivered encrypted with a user supplied crypth4gh public key.
 paths:
   /file:
     get:
-      description: Returns the requested file to the user
+      description: Returns the requested file to the user. Uses query parameters in order to handle files requested by the `filePath` entity.
       parameters:
         - in: header
-          description: "Public key used to re-encrypt the file (header) with. This should be supplied as the base64 encoding of the PEM (RFC 7468) encoding of the public key"
+          description: Public key used to re-encrypt the file (header) with. This should be supplied as the base64 encoding of the PEM (RFC 7468) encoding of the public key
           name: public_key
           required: true
           schema:
@@ -18,7 +19,7 @@ paths:
           schema:
             type: string
           required: true
-          description: Stable ID of the dataset
+          description: Dataset identifier
         - in: query
           name: fileId
           schema:
@@ -33,15 +34,14 @@ paths:
           description: File path of the file to download. It is an error to supply both filePath and fileId
         - in: query
           name: end
-          description: 'End of requested data in the form of the 0-index of the first octet not included in the
-                                 response. That is, data delivered will have octet indices in the closed-open set
-                                 [start,end). Defaults to end of file if not set'
+          description: End of requested data in the form of the 0-index of the first octet not included in the response. That is, data delivered will have octet indices in the closed-open set [start,end). Defaults to end of file if not set
           required: false
           schema:
             minimum: 0
             type: integer
         - in: query
           name: start
+          description: Start of the requested data. Defaults to start of file if not set
           required: false
           schema:
             default: 0
@@ -63,23 +63,23 @@ paths:
                 format: binary
           description: Successful partial file delivery
         "400":
-          description: Bad request i.e start larger than end
+          description: Bad request ex. start larger than end
         "401":
           description: Authentication failure
         "403":
           description: The user does not have access to the dataset
         "416":
-          description: Unsatisfiable range i.e. end larger than file size
+          description: Unsatisfiable range ex. start larger than the size of the file
         "500":
           description: Internal application error
       security:
         - bearerAuth: []
   /file/{fileId}:
     get:
-      description: Returns the requested file to the user
+      description: Returns the requested file to the user.
       parameters:
         - in: header
-          description: "Public key used to re-encrypt the file header with"
+          description: Public key used to re-encrypt the file (header) with. This should be supplied as the base64 encoding of the PEM (RFC 7468) encoding of the public key
           name: public_key
           required: true
           schema:
@@ -113,13 +113,13 @@ paths:
                 format: binary
           description: Successful partial file delivery
         "400":
-          description: Bad request i.e start larger than end
+          description: Bad request ex. start larger than end
         "401":
           description: Authentication failure
         "403":
           description: The user does not have access to the dataset
         "416":
-          description: Unsatisfiable range i.e. end larger than file size
+          description: Unsatisfiable range ex. start larger than the size of the file
         "500":
           description: Internal application error
       security:
@@ -150,7 +150,7 @@ paths:
           schema:
             type: string
           required: true
-          description: Stable ID of the dataset of interest
+          description: Dataset identifier
       responses:
         "200":
           content:
@@ -175,7 +175,7 @@ paths:
           schema:
             type: string
           required: true
-          description: Stable ID of the dataset of interest
+          description: Dataset identifier
       responses:
         "200":
           content:
@@ -193,14 +193,29 @@ paths:
           description: Internal application error
       security:
         - bearerAuth: []
-  /ready:
+  /health/ready:
     get:
-      description: Returns the status of the application, used by the Kubernets API to decide if traffic should be routed to the app
+      description: Returns the status of the application.
       responses:
         "200":
+          content:
+            application/json:
+              example:
+                {
+                  "c4ghService": "responding",
+                  "database": "responding",
+                  "oidcServer": "responding",
+                  "storageBackend": "responding",
+                }
           description: The service is operational
         "503":
           description: Unhealthy service
+  /health/live:
+    get:
+      description: Returns 200 as long as the main thread is running
+      responses:
+        "200":
+          description: The service is operational
 components:
   schemas:
     DatasetInfo:
@@ -226,7 +241,7 @@ components:
       properties:
         filePath:
           type: string
-          example: "samples/controls/sample1.cram.c4gh"
+          example: samples/controls/sample1.cram.c4gh
         size:
           type: integer
           format: int64