fix: swagger documentation update

- **build.py**: Added missing `file` parameter, fixed response schemas, added enum for kind, better examples
- **api.py**: Fixed securityDefinitions syntax, improved config endpoint documentation
- **auth.py**: Fixed incorrect summary, removed duplicate definitions, fixed path parameter syntax (from `schema: {type: string}` to `type: string`), added 400 responses

Author: d4rkstar

openserverless/rest/api.py

@@ -24,8 +24,10 @@ def info():
     """
     Info Endpoint
     ---
-    securityDefinitions:      
-        openwhiskBasicAuth:          
+    securityDefinitions:
+        openwhiskBasicAuth:
+            type: basic
+            description: OpenWhisk basic authentication using UUID:KEY format
     definitions:
       Message:
         type: object
@@ -93,15 +95,18 @@ def info():
 @app.route('/system/config')
 def config():
     """
-    Info Endpoint
+    Config Endpoint
     ---
     tags:
       - Config
+    summary: Get API configuration data
+    description: Returns basic configuration data used by this API
+    operationId: getConfig
     responses:
       200:
-        description: Config Endpoint Returns Basic Configuration Data used by this API.
+        description: Configuration data retrieved successfully
         schema:
-          $ref: '#/definitions/Message'     
+          $ref: '#/definitions/MessageData'
     """
     config = {
 

openserverless/rest/auth.py

@@ -28,63 +28,42 @@
 @ow_authorize(pass_user_data=True)
 def password(login, **kwargs):
     """
-    Update the user password patching the corresponding wsku/<login> entry.
+    Update User Password
     ---
-    tags: 
+    tags:
       - Authentication Api
-    summary: Login an OpenServerless user using login/password payload
-    operationId: patchOpsUser
+    summary: Update user password
+    description: Update the user password by patching the corresponding WhiskUser entry
+    operationId: updateUserPassword
     security:
         - openwhiskBasicAuth: []
     consumes:
         - application/json
-    definitions:
-      LoginUpdateData:
-        type: object
-        properties:
-          password:
-            type: string
-          new_password:
-            type: string
-        required:
-        - password
-        - new_password
-      MessageData:
-        type: object
-        properties:
-          message:
-            type: object
-          status: 
-            type: string
-      Message:
-        type: object
-        properties:
-          message:
-            type: string
-          status: 
-            type: string
     parameters:
     - in: path
       name: login
-      description: The username requiring the password update.
+      description: The username requiring the password update
       required: true
-      schema:
-       type: string   
+      type: string
     - in: body
-      name: User
-      description: the password update payload.
+      name: PasswordUpdate
+      description: Password update payload containing current and new password
       required: true
       schema:
-        $ref: '#/definitions/LoginUpdateData'                                         
+        $ref: '#/definitions/LoginUpdateData'
     responses:
       200:
-        description: Logged in User data
+        description: Password updated successfully
         schema:
           $ref: '#/definitions/MessageData'
+      400:
+        description: Bad request. Missing required fields.
+        schema:
+          $ref: '#/definitions/Message'
       401:
-        description: Access denied due to wrong credentials.
+        description: Unauthorized. Invalid credentials or authorization token.
         schema:
-          $ref: '#/definitions/Message'         
+          $ref: '#/definitions/Message'
     """     
     update_data = request.get_json()
 
@@ -99,30 +78,35 @@ def password(login, **kwargs):
 @app.route('/system/api/v1/auth',methods=['POST'])
 def login():
     """
-    Perform the user Authentication relying on wsku metadata stored into internal CouchDB.
+    User Authentication
     ---
-    tags: 
+    tags:
       - Authentication Api
-    summary: Login an OpenServerless user using login/password payload
-    operationId: loginOpsUser
+    summary: Authenticate user with login credentials
+    description: Perform user authentication using credentials stored in CouchDB metadata
+    operationId: authenticateUser
     consumes:
         - application/json
     parameters:
     - in: body
-      name: User
-      description: The user to login.
+      name: LoginCredentials
+      description: User login credentials
       required: true
       schema:
-        $ref: '#/definitions/LoginData'                                         
+        $ref: '#/definitions/LoginData'
     responses:
       200:
-        description: Logged in User data
+        description: Authentication successful. Returns user data including environment variables and quota.
         schema:
           $ref: '#/definitions/MessageData'
+      400:
+        description: Bad request. Missing login or password.
+        schema:
+          $ref: '#/definitions/Message'
       401:
-        description: Access denied due to wrong credentials.
+        description: Unauthorized. Invalid credentials.
         schema:
-          $ref: '#/definitions/Message'         
+          $ref: '#/definitions/Message'
     """    
     login_data = request.get_json()
     auth_service = AuthService()

openserverless/rest/build.py

@@ -62,21 +62,48 @@ def build():
         required: true
         schema:
           type: object
+          required:
+            - source
+            - target
+            - kind
           properties:
             source:
               type: string
-              description: Source for the build
+              description: Source image for the build (e.g., ghcr.io/nuvolaris/openserverless-runtime-python:3.12)
+              example: "ghcr.io/nuvolaris/openserverless-runtime-python:3.12"
             target:
               type: string
-              description: Target for the build
+              description: Target image name in format username:tag (must match authenticated user)
+              example: "myuser:custom-tag"
             kind:
               type: string
-              description: Kind of the build
+              description: Runtime kind (python, nodejs, java, php, go, ruby, dotnet)
+              enum: [python, nodejs, java, php, go, ruby, dotnet]
+              example: "python"
+            file:
+              type: string
+              description: Base64-encoded requirements file (optional, e.g., requirements.txt for Python)
+              example: "cmVxdWVzdHM9PTIuMzEuMA=="
     responses:
       200:
         description: Build process initiated successfully.
         schema:
-          $ref: '#/definitions/Message'
+          type: object
+          properties:
+            message:
+              type: string
+              example: "Build process initiated successfully. Job: build-myuser-abc123"
+            data:
+              type: object
+              properties:
+                id:
+                  type: string
+                  description: Unique build ID
+                  example: "550e8400-e29b-41d4-a716-446655440000"
+                job_name:
+                  type: string
+                  description: Kubernetes job name
+                  example: "build-myuser-abc123"
       400:
         description: Bad Request. Missing or invalid parameters.
         schema:
@@ -168,46 +195,38 @@ def clean():
                 default: 24
               
     responses:
-      '200':
+      200:
         description: Successfully cleaned up old build jobs.
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                message:
-                  type: string
-                  example: Cleaned up 5 jobs successfully.
-      '400':
+        schema:
+          type: object
+          properties:
+            message:
+              type: string
+              example: "Cleaned up 5 jobs successfully."
+      400:
         description: Bad request. No JSON payload provided for cleanup.
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                error:
-                  type: string
-                  example: No JSON payload provided for cleanup.
-      '401':
+        schema:
+          type: object
+          properties:
+            error:
+              type: string
+              example: "No JSON payload provided for cleanup."
+      401:
         description: Unauthorized. User environment not found.
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                error:
-                  type: string
-                  example: User environment not found
-      '500':
+        schema:
+          type: object
+          properties:
+            error:
+              type: string
+              example: "User environment not found"
+      500:
         description: Internal server error. Failed to clean up old build jobs.
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                error:
-                  type: string
-                  example: Failed to clean up old build jobs.
+        schema:
+          type: object
+          properties:
+            error:
+              type: string
+              example: "Failed to clean up old build jobs."
     """
 
     auth_result = authorize()