pp

Author: prkhrkat

specs/application.yaml

@@ -1,104 +1,217 @@
-openapi: "3.0.0"
+openapi: 3.0.3
 info:
   version: 1.0.0
-  title: Devtron Labs
-  description: Devtron API for application management
+  title: Devtron Application Management API
+  description: |
+    This API provides functionality for managing applications in Devtron, including
+    creating, updating, and listing applications, as well as managing application
+    configurations, environments, and deployments.
   termsOfService: https://devtron.ai/terms/
   contact:
-    name: Devtron Labs
+    name: Devtron Support
     email: [email protected]
-    url: https://devtron.ai
+    url: https://devtron.ai/support
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
+
 servers:
-  - url: http://localhost:8080/orchestrator
+  - url: /orchestrator
+    description: Devtron Orchestrator API Server
+
+tags:
+  - name: Applications
+    description: Operations related to application management
+  - name: Environments
+    description: Operations related to application environments
+  - name: Deployments
+    description: Operations related to application deployments
+
 paths:
   /core/v1beta1/application:
     post:
-      description: create new application
+      tags:
+        - Applications
+      summary: Create a new application
+      description: Creates a new application in the Devtron system with the provided configuration.
+      operationId: createApplication
       requestBody:
-        description: json as request body
+        description: Application creation request
         required: true
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/CreateAppRequest'
       responses:
         '200':
-          description: App create response
+          description: Application created successfully
           content:
             application/json:
               schema:
-                properties:
-                  code:
-                    type: integer
-                    description: status code
-                  status:
-                    type: string
-                    description: status
-                  result:
-                    type: string
-                    description: success message
-        default:
-          description: unexpected error
+                $ref: '#/components/schemas/ApiResponse'
+        '400':
+          description: Invalid request format or missing required fields
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '409':
+          description: Application with the same name already exists
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Internal server error
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+      security:
+        - bearerAuth: []
+
   /app/edit:
     post:
-      description: update application projects and labels
+      tags:
+        - Applications
+      summary: Update application
+      description: Updates an existing application's configuration including projects and labels.
+      operationId: updateApplication
       requestBody:
-        description: json as request body
+        description: Application update request
         required: true
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/App'
       responses:
         '200':
-          description: App update response
+          description: Application updated successfully
           content:
             application/json:
               schema:
-                properties:
-                  code:
-                    type: integer
-                    description: status code
-                  status:
-                    type: string
-                    description: status
-                  result:
-                    type: object
-                    description: string
-                    allOf:
-                      - type: object
-                        properties:
-                          id:
-                            type: integer
-                            description: unique application id
-                        required:
-                          - id
-                      - $ref: '#/components/schemas/App'
-        default:
-          description: unexpected error
+                $ref: '#/components/schemas/ApiResponse'
+        '400':
+          description: Invalid request format or missing required fields
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: Application not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+      security:
+        - bearerAuth: []
 
   /app/list:
     post:
-      description: app listing, collection of deployed applications or undeployed or incomplete configured apps.
+      tags:
+        - Applications
+      summary: List applications
+      description: |
+        Retrieves a paginated list of applications based on the provided filters.
+        Can return deployed applications, undeployed applications, or applications with incomplete configurations.
+      operationId: listApplications
       requestBody:
-        description: json as request body
+        description: Application listing filters
         required: true
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/AppListingRequest'
       responses:
+        '200':
+          description: List of applications retrieved successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AppListResponse'
+        '400':
+          description: Invalid request parameters
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+      security:
+        - bearerAuth: []
+
+  /app/details/{appId}:
+    get:
+      tags:
+        - Applications
+      summary: Get application details
+      description: Retrieves detailed information about a specific application including its configurations and status.
+      operationId: getApplicationDetails
+      parameters:
+        - name: appId
+          in: path
+          description: ID of the application to retrieve
+          required: true
+          schema:
+            type: integer
+            format: int64
+            minimum: 1
+          example: 12345
+      responses:
+        '200':
+          description: Application details retrieved successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AppDetails'
+        '401':
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: Application not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+      security:
+        - bearerAuth: []
         '200':
           description: App create response
           content: