From 049a7f4b80578392272d6f53b10131ada5fd340d Mon Sep 17 00:00:00 2001
From: Yury <yury@4gl.io>
Date: Tue, 29 Oct 2024 12:02:26 +0300
Subject: [PATCH] chore(swagger): improved description

---
 api/public/swagger.yaml     | 20 ++++++++++----------
 api/src/controllers/code.ts | 17 +++++++++--------
 api/src/controllers/stp.ts  |  4 ++--
 3 files changed, 21 insertions(+), 20 deletions(-)

diff --git a/api/public/swagger.yaml b/api/public/swagger.yaml
index 04dacd3..922b2f4 100644
--- a/api/public/swagger.yaml
+++ b/api/public/swagger.yaml
@@ -98,11 +98,11 @@ components:
             properties:
                 code:
                     type: string
-                    description: 'Code of program'
-                    example: '* Code HERE;'
+                    description: 'The code to be executed'
+                    example: '* Your Code HERE;'
                 runTime:
                     $ref: '#/components/schemas/RunTimeType'
-                    description: 'runtime for program'
+                    description: 'The runtime for the code - eg SAS, JS, PY or R'
                     example: js
             required:
                 - code
@@ -113,7 +113,7 @@ components:
             properties:
                 sessionId:
                     type: string
-                    description: "Session ID (SAS WORK folder) used to execute code.\nThis session ID should be used to poll job status."
+                    description: "The SessionId is the name of the temporary folder used to store the outputs.\nFor SAS, this would be the SASWORK folder. Can be used to poll job status.\nThis session ID should be used to poll job status."
                     example: '{ sessionId: ''20241028074744-54132-1730101664824'' }'
             required:
                 - sessionId
@@ -123,11 +123,11 @@ components:
             properties:
                 code:
                     type: string
-                    description: 'Code of program'
-                    example: '* Code HERE;'
+                    description: 'The code to be executed'
+                    example: '* Your Code HERE;'
                 runTime:
                     $ref: '#/components/schemas/RunTimeType'
-                    description: 'runtime for program'
+                    description: 'The runtime for the code - eg SAS, JS, PY or R'
                     example: sas
                 expiresAfterMins:
                     type: number
@@ -846,7 +846,7 @@ paths:
                             schema:
                                 $ref: '#/components/schemas/TriggerCodeResponse'
             description: 'Trigger Code on the Specified Runtime'
-            summary: 'Trigger Code and Return Session Id not awaiting for the job completion'
+            summary: 'Triggers code and returns SessionId immediately - does not wait for job completion'
             tags:
                 - Code
             security:
@@ -1852,7 +1852,7 @@ paths:
                     bearerAuth: []
             parameters:
                 -
-                    description: 'Location of code in SASjs Drive'
+                    description: 'Location of Stored Program in SASjs Drive.'
                     in: query
                     name: _program
                     required: true
@@ -1860,7 +1860,7 @@ paths:
                         type: string
                     example: /Projects/myApp/some/program
                 -
-                    description: 'Optional query param for setting debug mode, which will return the session log.'
+                    description: 'Optional query param for setting debug mode (returns the session log in the response body).'
                     in: query
                     name: _debug
                     required: false
diff --git a/api/src/controllers/code.ts b/api/src/controllers/code.ts
index 11912d9..4620ba5 100644
--- a/api/src/controllers/code.ts
+++ b/api/src/controllers/code.ts
@@ -10,12 +10,12 @@ import {
 
 interface ExecuteCodePayload {
   /**
-   * Code of program
-   * @example "* Code HERE;"
+   * The code to be executed
+   * @example "* Your Code HERE;"
    */
   code: string
   /**
-   * runtime for program
+   * The runtime for the code - eg SAS, JS, PY or R
    * @example "js"
    */
   runTime: RunTimeType
@@ -23,12 +23,12 @@ interface ExecuteCodePayload {
 
 interface TriggerCodePayload {
   /**
-   * Code of program
-   * @example "* Code HERE;"
+   * The code to be executed
+   * @example "* Your Code HERE;"
    */
   code: string
   /**
-   * runtime for program
+   * The runtime for the code - eg SAS, JS, PY or R
    * @example "sas"
    */
   runTime: RunTimeType
@@ -42,7 +42,8 @@ interface TriggerCodePayload {
 
 interface TriggerCodeResponse {
   /**
-   * Session ID (SAS WORK folder) used to execute code.
+   * The SessionId is the name of the temporary folder used to store the outputs.
+   * For SAS, this would be the SASWORK folder. Can be used to poll job status.
    * This session ID should be used to poll job status.
    * @example "{ sessionId: '20241028074744-54132-1730101664824' }"
    */
@@ -74,7 +75,7 @@ export class CodeController {
 
   /**
    * Trigger Code on the Specified Runtime
-   * @summary Trigger Code and Return Session Id not awaiting for the job completion
+   * @summary Triggers code and returns SessionId immediately - does not wait for job completion
    */
   @Post('/trigger')
   public async triggerCode(
diff --git a/api/src/controllers/stp.ts b/api/src/controllers/stp.ts
index bd6719e..dbc881d 100644
--- a/api/src/controllers/stp.ts
+++ b/api/src/controllers/stp.ts
@@ -30,8 +30,8 @@ export class STPController {
    * https://server.sasjs.io/storedprograms
    *
    * @summary Execute a Stored Program, returns _webout and (optionally) log.
-   * @param _program Location of code in SASjs Drive
-   * @param _debug Optional query param for setting debug mode, which will return the session log.
+   * @param _program Location of Stored Program in SASjs Drive.
+   * @param _debug Optional query param for setting debug mode (returns the session log in the response body).
    * @example _program "/Projects/myApp/some/program"
    * @example _debug 131
    */