openapi: 3.0.0
info:
  title: CDW Tools API
  description: Free financial calculators and productivity tools API
  version: 1.0.0
  contact:
    name: CDW Tools Support
    url: https://tools.connectdigitalworld.com
  x-logo:
    url: https://tools.connectdigitalworld.com/logo.png

servers:
  - url: https://tools.connectdigitalworld.com/api
    description: Production server

paths:
  /tools:
    get:
      summary: Get all available tools
      description: Returns a list of all financial calculators and utilities
      operationId: getAllTools
      parameters:
        - name: category
          in: query
          description: Filter tools by category
          schema:
            type: string
            enum:
              - finance
              - calculator
              - developer-tools
              - security
              - utility
              - converter
              - generator
        - name: limit
          in: query
          description: Maximum number of tools to return
          schema:
            type: integer
            default: 10
        - name: offset
          in: query
          description: Number of tools to skip
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tool'
                  totalCount:
                    type: integer

  /tools/{toolId}:
    get:
      summary: Get specific tool details
      description: Returns detailed information about a specific tool
      operationId: getToolById
      parameters:
        - name: toolId
          in: path
          required: true
          schema:
            type: string
          description: Tool ID (e.g., 'emi-calculator')
      responses:
        '200':
          description: Tool found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/ToolDetail'
        '404':
          description: Tool not found

  /tools/search:
    get:
      summary: Search tools
      description: Search for tools by keyword
      operationId: searchTools
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Search query
        - name: category
          in: query
          schema:
            type: string
          description: Filter by category
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tool'
                  resultCount:
                    type: integer

  /tools/categories:
    get:
      summary: Get all tool categories
      description: Returns list of available tool categories
      operationId: getCategories
      responses:
        '200':
          description: List of categories
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  categories:
                    type: array
                    items:
                      type: string

  /calculators/emi:
    post:
      summary: Calculate EMI
      description: Calculate Equated Monthly Installment for a loan
      operationId: calculateEMI
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                principal:
                  type: number
                  description: Loan amount in currency
                rate:
                  type: number
                  description: Annual interest rate (percentage)
                months:
                  type: integer
                  description: Loan tenure in months
              required:
                - principal
                - rate
                - months
      responses:
        '200':
          description: EMI calculation result
          content:
            application/json:
              schema:
                type: object
                properties:
                  emi:
                    type: number
                  totalAmount:
                    type: number
                  totalInterest:
                    type: number
                  currency:
                    type: string

  /calculators/compound-interest:
    post:
      summary: Calculate Compound Interest
      description: Calculate compound interest for investments
      operationId: calculateCompoundInterest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                principal:
                  type: number
                  description: Initial investment amount
                rate:
                  type: number
                  description: Annual interest rate (percentage)
                years:
                  type: integer
                  description: Investment period in years
                frequency:
                  type: string
                  enum: ["yearly", "half-yearly", "quarterly", "monthly"]
                  description: Compounding frequency
              required:
                - principal
                - rate
                - years
                - frequency
      responses:
        '200':
          description: Compound interest result
          content:
            application/json:
              schema:
                type: object
                properties:
                  finalAmount:
                    type: number
                  interestEarned:
                    type: number
                  currency:
                    type: string

  /tools/recommend:
    post:
      summary: Get tool recommendations
      description: Get AI-powered tool recommendations based on user needs
      operationId: recommendTools
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: User's need or question
              required:
                - query
      responses:
        '200':
          description: Recommended tools
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  recommendations:
                    type: array
                    items:
                      type: object
                      properties:
                        tool:
                          $ref: '#/components/schemas/Tool'
                        relevanceScore:
                          type: number
                        reason:
                          type: string

components:
  schemas:
    Tool:
      type: object
      properties:
        id:
          type: string
          description: Unique tool identifier
        name:
          type: string
          description: Tool name
        title:
          type: string
          description: Tool display title
        description:
          type: string
          description: Tool description
        category:
          type: array
          items:
            type: string
          description: Tool categories
        tags:
          type: array
          items:
            type: string
          description: Tool tags for searching
        url:
          type: string
          format: uri
          description: Direct link to tool
        features:
          type: array
          items:
            type: string
          description: Tool features list

    ToolDetail:
      allOf:
        - $ref: '#/components/schemas/Tool'
        - type: object
          properties:
            inputTypes:
              type: array
              items:
                type: string
              description: Types of input the tool accepts
            outputTypes:
              type: array
              items:
                type: string
              description: Types of output the tool produces
            useCase:
              type: string
              description: Primary use case
            targetAudience:
              type: array
              items:
                type: string
              description: Target user groups
            isActive:
              type: boolean
              description: Tool availability status
            apiEndpoint:
              type: string
              format: uri
              description: API endpoint for tool (if available)

tags:
  - name: Tools
    description: Tool listing and search
  - name: Calculators
    description: Financial calculators
  - name: Recommendations
    description: AI-powered recommendations