openapi: 3.0.3
info:
  title: Shoehorn Analytics API
  description: |
    Aggregate statistics across the catalog, search usage, ownership,
    lifecycle, and language breakdowns.
  version: 1.0.0

servers:
  - url: https://shoehorn.example.com/api/v1
    description: Production

paths:
  /stats:
    get:
      summary: Get catalog statistics
      tags: [Statistics]
      responses:
        '200':
          description: Aggregate catalog metrics
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_entities: { type: integer }
                  by_type: { type: object, additionalProperties: { type: integer } }
                  by_lifecycle: { type: object, additionalProperties: { type: integer } }
                  by_tier: { type: object, additionalProperties: { type: integer } }

  /stats/entity-types:
    get:
      summary: Get entity type breakdown
      tags: [Statistics]
      responses:
        '200':
          description: Count by entity type

  /stats/languages:
    get:
      summary: Get programming language distribution
      tags: [Statistics]
      responses:
        '200':
          description: Language statistics

  /stats/lifecycle:
    get:
      summary: Get lifecycle stage distribution
      tags: [Statistics]
      responses:
        '200':
          description: Count by lifecycle stage

  /stats/teams:
    get:
      summary: Get team ownership statistics
      tags: [Statistics]
      responses:
        '200':
          description: Entities per team

  /stats/unowned:
    get:
      summary: Get unowned entities
      tags: [Statistics]
      responses:
        '200':
          description: Entities without an owner

  /analytics/search:
    get:
      summary: Get search analytics
      tags: [Search analytics]
      responses:
        '200':
          description: Search usage analytics

  /analytics/search/{period}:
    get:
      summary: Get search analytics by period
      tags: [Search analytics]
      parameters:
        - name: period
          in: path
          required: true
          schema: { type: string, enum: [7d, 30d, 90d] }
      responses:
        '200':
          description: Search analytics for period
