qcopenapi

openapi: 3.0.3
info:
  title: Loan Management API
  version: 1.0.0
  description: API documentation for Loan Management System
  contact:
    email: [email protected]
  license:
    name: MIT License
paths:
  /auth/login/:
    post:
      operationId: authenticate_user
      description: Authenticate user and return JWT token.
      summary: Login User
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomTokenObtainPair'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CustomTokenObtainPair'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CustomTokenObtainPair'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomTokenObtainPair'
          description: User authenticated successfully.
        '400':
          description: Invalid credentials.
        '500':
          description: Server error occurred.
  /auth/register/:
    post:
      operationId: register_user
      description: Register a new user on the platform - either as a Customer or an
        Admin.
      summary: Register User
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRegistration'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UserRegistration'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UserRegistration'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserRegistrationResponse'
          description: User registered successfully.
        '400':
          description: Invalid registration data.
        '500':
          description: Server error occurred.
  /auth/token/refresh/:
    post:
      operationId: auth_token_refresh_create
      description: |-
        Takes a refresh type JSON web token and returns an access type JSON web
        token if the refresh token is valid.
      tags:
      - auth
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRefresh'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenRefresh'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/TokenRefresh'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenRefresh'
          description: ''
  /loan/:
    post:
      operationId: loan_create
      description: Submit a new loan application for the authenticated customer.
      summary: Submit a new loan application
      tags:
      - Loans
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoanApplicationRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/LoanApplicationRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/LoanApplicationRequest'
        required: true
      security:
      - jwtAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoanApplicationResponse'
          description: Loan application created successfully
        '400':
          description: Invalid request data
        '403':
          description: Permission denied
        '500':
          description: Internal server error
  /loan/{id}/:
    get:
      operationId: customer_loan_retrieve
      description: Retrieve a specific loan application by ID for the authenticated
        customer.
      summary: Retrieve a specific loan application
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      tags:
      - Loans
      security:
      - jwtAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoanApplicationResponse'
          description: Loan application details
        '404':
          description: Loan application not found
        '403':
          description: Permission denied
        '500':
          description: Internal server error
  /loans/:
    get:
      operationId: admin_all_loans
      description: Admin can view all loan applications
      summary: Retrieve all loan applications - Admin Only
      tags:
      - Loans
      security:
      - jwtAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoanApplication'
          description: List of all loan applications
        '404':
          description: No loan applications found
        '403':
          description: Permission denied
        '500':
          description: Internal server error
  /loans/{id}/:
    get:
      operationId: admin_loan_retrieve
      description: Admin can view details of a specific loan application by ID
      summary: Retrieve a specific loan application - Admin Only
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      tags:
      - Loans
      security:
      - jwtAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoanApplication'
          description: Loan application details
        '403':
          description: Permission denied
        '500':
          description: Internal server error
  /loans/{id}/approve/:
    post:
      operationId: admin_loan_approve
      description: Approve a loan application
      summary: Approve a loan application - Admin Only
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      tags:
      - Loans
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoanApplication'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/LoanApplication'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/LoanApplication'
        required: true
      security:
      - jwtAuth: []
      responses:
        '200':
          description: Loan application approved
        '400':
          description: Error approving loan application
        '403':
          description: Permission denied
        '500':
          description: Internal server error
  /loans/{id}/flag/:
    post:
      operationId: loans_flag_create
      description: Admin flags a loan application for potential fraud
      summary: Flag a loan application for potential fraud - Admin Only
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      tags:
      - Loans
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoanApplication'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/LoanApplication'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/LoanApplication'
        required: true
      security:
      - jwtAuth: []
      responses:
        '201':
          description: Loan application flagged for fraud
        '400':
          description: Error flagging loan application
        '403':
          description: Permission denied
        '500':
          description: Internal server error
  /loans/{id}/reject/:
    post:
      operationId: loans_reject_create
      description: Reject a loan application by ID
      summary: Reject a loan application - Admin Only
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      tags:
      - Loans
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoanApplication'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/LoanApplication'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/LoanApplication'
        required: true
      security:
      - jwtAuth: []
      responses:
        '200':
          description: Loan application rejected
        '400':
          description: Error rejecting loan application
        '403':
          description: Permission denied
        '500':
          description: Internal server error
  /loans/flagged/:
    get:
      operationId: loans_flagged_retrieve
      description: Admin can view all flagged loan applications
      summary: View all flagged loan applications - Admin Only
      tags:
      - Loans
      security:
      - jwtAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoanApplicationResponse'
          description: List of flagged loans
        '404':
          description: No flagged loans found
        '403':
          description: Permission denied
        '500':
          description: Internal server error
  /loans/requests/:
    get:
      operationId: customer_loan_retrieve_2
      description: Retrieve all loan applications for the authenticated customer.
      summary: View all my loan applications
      tags:
      - Loans
      security:
      - jwtAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoanApplicationResponse'
          description: List of loan applications
        '404':
          description: Loan application not found
        '403':
          description: Permission denied
        '500':
          description: Internal server error
components:
  schemas:
    CustomTokenObtainPair:
      type: object
      properties:
        username:
          type: string
          writeOnly: true
        password:
          type: string
          writeOnly: true
      required:
      - password
      - username
    LoanApplication:
      type: object
      description: |-
        Serializer for loan applications - used only for admin or internal APIs.
        Converts loan application model instances to JSON format and vice versa.
      properties:
        amount_requested:
          type: string
          format: decimal
          pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
          description: Amount needed by the customer for the loan
        purpose:
          allOf:
          - $ref: '#/components/schemas/PurposeEnum'
          description: |-
            Purpose of the loan application

            * `PERSONAL` - Personal
            * `BUSINESS` - Business
            * `EDUCATION` - Education
            * `MEDICAL` - Medical
            * `OTHER` - Other
        status:
          allOf:
          - $ref: '#/components/schemas/StatusEnum'
          description: |-
            Current status of the loan application

            * `PENDING` - Pending
            * `APPROVED` - Approved
            * `REJECTED` - Rejected
            * `FLAGGED` - Flagged for Fraud
        date_applied:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when the loan application was submitted
        date_updated:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when the loan application was last updated
        user:
          type: integer
          description: Customer applying for the loan
      required:
      - amount_requested
      - date_applied
      - date_updated
      - purpose
      - user
    LoanApplicationRequest:
      type: object
      description: |-
        Serializer for loan application requests.
        Validates and converts incoming data to a format suitable for creating a loan application.
      properties:
        user:
          type: integer
          readOnly: true
          description: Customer applying for the loan
        amount_requested:
          type: string
          format: decimal
          pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
          description: Amount needed by the customer for the loan
        purpose:
          allOf:
          - $ref: '#/components/schemas/PurposeEnum'
          description: |-
            Purpose of the loan application

            * `PERSONAL` - Personal
            * `BUSINESS` - Business
            * `EDUCATION` - Education
            * `MEDICAL` - Medical
            * `OTHER` - Other
      required:
      - amount_requested
      - purpose
      - user
    LoanApplicationResponse:
      type: object
      description: |-
        Serializer for loan application responses.
        Converts loan application model instances to a simplified JSON format.
      properties:
        full_name:
          type: string
        amount:
          type: string
          format: decimal
          pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
        purpose:
          type: string
        status:
          type: string
        date_applied:
          type: string
          format: date-time
        date_updated:
          type: string
          format: date-time
      required:
      - amount
      - date_applied
      - full_name
      - purpose
      - status
    PurposeEnum:
      enum:
      - PERSONAL
      - BUSINESS
      - EDUCATION
      - MEDICAL
      - OTHER
      type: string
      description: |-
        * `PERSONAL` - Personal
        * `BUSINESS` - Business
        * `EDUCATION` - Education
        * `MEDICAL` - Medical
        * `OTHER` - Other
    RoleEnum:
      enum:
      - ADMIN
      - CUSTOMER
      type: string
      description: |-
        * `ADMIN` - Admin
        * `CUSTOMER` - Customer
    StatusEnum:
      enum:
      - PENDING
      - APPROVED
      - REJECTED
      - FLAGGED
      type: string
      description: |-
        * `PENDING` - Pending
        * `APPROVED` - Approved
        * `REJECTED` - Rejected
        * `FLAGGED` - Flagged for Fraud
    TokenRefresh:
      type: object
      properties:
        access:
          type: string
          readOnly: true
        refresh:
          type: string
          writeOnly: true
      required:
      - access
      - refresh
    UserRegistration:
      type: object
      properties:
        username:
          type: string
          description: Required. 150 characters or fewer. Letters, digits and @/./+/-/_
            only.
          pattern: ^[\w.@+-]+$
          maxLength: 150
        first_name:
          type: string
          description: The first name of the user. Required for all users.
          maxLength: 30
        last_name:
          type: string
          description: The last name of the user. Required for all users.
          maxLength: 30
        email:
          type: string
          format: email
          title: Email Address
          description: The email address of the user. Required for all users.
          maxLength: 254
        role:
          $ref: '#/components/schemas/RoleEnum'
        password:
          type: string
          writeOnly: true
        phone_number:
          type: string
          nullable: true
          description: User's phone number - must be 11 digits, without the country
            code. Required for customers.
          maxLength: 11
        date_of_birth:
          type: string
          format: date
          nullable: true
          description: The date of birth of the user. Required for customers.
      required:
      - email
      - first_name
      - last_name
      - password
      - role
      - username
    UserRegistrationResponse:
      type: object
      properties:
        full_name:
          type: string
          readOnly: true
        username:
          type: string
          description: Required. 150 characters or fewer. Letters, digits and @/./+/-/_
            only.
          pattern: ^[\w.@+-]+$
          maxLength: 150
        role:
          $ref: '#/components/schemas/RoleEnum'
      required:
      - full_name
      - username
  securitySchemes:
    jwtAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT