Merge pull request #2341 from deepikagandla7456/2316

[FEATURE] Build Comprehensive API Versioning Strategy with Backward-Compatible Migration

Author: AseemPrasad

api/specs/v1.yaml

@@ -0,0 +1,306 @@
+openapi: 3.0.0
+info:
+  title: LegalAssist AI API
+  description: |
+    Comprehensive legal case analysis and deadline management API.
+    
+    ## API Versions
+    - **v1**: Initial stable release (Deprecated as of 2025-12-31)
+    - **v2**: Current stable release with enhanced features
+    
+    ## Versioning
+    This API uses URL-based versioning. Specify the version in the URL path:
+    - `/api/v1/*` - Version 1 (deprecated)
+    - `/api/v2/*` - Version 2 (current)
+    
+    ## Deprecation
+    v1 will be sunset on December 31, 2025. Please migrate to v2.
+    See the migration guide at https://docs.legalassist.ai/migration/v1-to-v2
+  
+  version: "1.0"
+  contact:
+    name: LegalAssist AI Support
+    email: support@legalassist.ai
+  license:
+    name: MIT
+    url: https://opensource.org/licenses/MIT
+
+servers:
+  - url: https://api.legalassist.ai/api/v1
+    description: Version 1 API (deprecated)
+  - url: https://api.legalassist.ai/api/v2
+    description: Version 2 API (current)
+  - url: http://localhost:8000/api/v1
+    description: Local development v1
+  - url: http://localhost:8000/api/v2
+    description: Local development v2
+
+security:
+  - bearerAuth: []
+  - apiKeyAuth: []
+
+tags:
+  - name: Cases
+    description: Case management operations
+  - name: Documents
+    description: Document upload and management
+  - name: Deadlines
+    description: Deadline tracking and management
+  - name: Auth
+    description: Authentication and authorization
+  - name: Analytics
+    description: Analytics and reporting
+
+paths:
+  /cases:
+    get:
+      tags: [Cases]
+      summary: List cases
+      description: Get a paginated list of cases for the authenticated user
+      operationId: listCases
+      parameters:
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 1
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 20
+            maximum: 100
+        - name: status
+          in: query
+          schema:
+            type: string
+            enum: [active, pending, closed, archived]
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CaseList'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
+  /cases/{case_id}:
+    get:
+      tags: [Cases]
+      summary: Get case details
+      operationId: getCase
+      parameters:
+        - name: case_id
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Case'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+    delete:
+      tags: [Cases]
+      summary: Delete case
+      operationId: deleteCase
+      parameters:
+        - name: case_id
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        '204':
+          description: Case deleted
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+  /documents:
+    post:
+      tags: [Documents]
+      summary: Upload document
+      operationId: uploadDocument
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                file:
+                  type: string
+                  format: binary
+                case_id:
+                  type: integer
+      responses:
+        '201':
+          description: Document uploaded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Document'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+
+  /deadlines:
+    get:
+      tags: [Deadlines]
+      summary: List deadlines
+      operationId: listDeadlines
+      parameters:
+        - name: upcoming_only
+          in: query
+          schema:
+            type: boolean
+            default: false
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DeadlineList'
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: JWT token from /api/v1/auth/token
+    apiKeyAuth:
+      type: apiKey
+      in: header
+      name: X-API-Key
+      description: API key from /api/v1/auth/api-keys
+
+  schemas:
+    Case:
+      type: object
+      properties:
+        id:
+          type: integer
+        case_number:
+          type: string
+          deprecated: true
+          description: Use reference_id instead (v2+)
+        reference_id:
+          type: string
+          description: Unique case reference (v2+)
+        title:
+          type: string
+        case_type:
+          type: string
+        status:
+          type: string
+          enum: [active, pending, closed, archived]
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    CaseList:
+      type: object
+      properties:
+        cases:
+          type: array
+          items:
+            $ref: '#/components/schemas/Case'
+        total:
+          type: integer
+        page:
+          type: integer
+        limit:
+          type: integer
+
+    Document:
+      type: object
+      properties:
+        id:
+          type: integer
+        case_id:
+          type: integer
+        filename:
+          type: string
+        content_type:
+          type: string
+        uploaded_at:
+          type: string
+          format: date-time
+
+    Deadline:
+      type: object
+      properties:
+        id:
+          type: integer
+        case_id:
+          type: integer
+        deadline_type:
+          type: string
+        deadline_date:
+          type: string
+          format: date
+        description:
+          type: string
+        completed:
+          type: boolean
+
+    DeadlineList:
+      type: object
+      properties:
+        deadlines:
+          type: array
+          items:
+            $ref: '#/components/schemas/Deadline'
+        total:
+          type: integer
+
+  responses:
+    Unauthorized:
+      description: Authentication required
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error:
+                type: string
+              message:
+                type: string
+
+    NotFound:
+      description: Resource not found
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error:
+                type: string
+              message:
+                type: string
+
+    BadRequest:
+      description: Invalid request
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error:
+                type: string
+              message:
+                type: string
+
+deprecated: true
+x-sunset-date: "2025-12-31"
+x-migration-guide: https://docs.legalassist.ai/migration/v1-to-v2