openapi: 3.0.3
info:
  title: FootViz API
  description: Modern Django REST Framework API for the FootViz application.
  version: 3.0.0
servers:
  - url: http://localhost:8000/api
paths:
  /countries/:
    get:
      summary: Get Countries
      description: Returns a list of all countries.
      responses:
        '200':
          description: An array of countries.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
                    code:
                      type: string
                    league_name:
                      type: string
  /countries/{id}/:
    get:
      summary: Get Country by ID
      description: Returns a specific country by ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: A country object.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                  code:
                    type: string
                  league_name:
                    type: string

  /teams/:
    get:
      summary: Get Teams
      description: Returns a list of teams.
      parameters:
        - name: country
          in: query
          required: false
          schema:
            type: integer
          description: Filter teams by country ID
      responses:
        '200':
          description: An array of teams.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
                    country:
                      type: integer
                    country_name:
                      type: string

  /teams/{id}/:
    get:
      summary: Get Team by ID
      description: Returns a specific team by ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: A team object.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                  country:
                    type: integer
                  country_name:
                    type: string

  /players/:
    get:
      summary: Get Players
      description: Returns a list of players.
      parameters:
        - name: search
          in: query
          required: false
          schema:
            type: string
          description: Search players by name
      responses:
        '200':
          description: An array of players.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
                    team_name:
                      type: string
                    country_name:
                      type: string
                    age:
                      type: integer
                      nullable: true
                    date_of_birth:
                      type: string
                      format: date
                      nullable: true
                    height:
                      type: integer
                      nullable: true
                    nationality:
                      type: string
                      nullable: true
                    positions:
                      type: string
                      nullable: true
                    image_url:
                      type: string
                      format: uri
                      nullable: true

  /players/{id}/:
    get:
      summary: Get Player by ID
      description: Returns a specific player by ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: A player object.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                  team_name:
                    type: string
                  country_name:
                    type: string
                  age:
                    type: integer
                    nullable: true
                  date_of_birth:
                    type: string
                    format: date
                    nullable: true
                  height:
                    type: integer
                    nullable: true
                  nationality:
                    type: string
                    nullable: true
                  positions:
                    type: string
                    nullable: true
                  image_url:
                    type: string
                    format: uri
                    nullable: true

  /player-stats/:
    get:
      summary: Get Player Statistics
      description: Returns a list of player statistics.
      parameters:
        - name: player
          in: query
          required: false
          schema:
            type: integer
          description: Filter stats by player ID
        - name: team
          in: query
          required: false
          schema:
            type: integer
          description: Filter stats by team ID
        - name: tournament
          in: query
          required: false
          schema:
            type: string
          description: Filter stats by tournament
      responses:
        '200':
          description: An array of player statistics.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    player:
                      type: integer
                    player_name:
                      type: string
                    team:
                      type: integer
                    team_name:
                      type: string
                    tournament:
                      type: string
                    appearances:
                      type: string
                      nullable: true
                    minutes_played:
                      type: integer
                      nullable: true
                    goals:
                      type: integer
                      nullable: true
                    assists:
                      type: integer
                      nullable: true
                    tackles:
                      type: number
                      format: float
                      nullable: true
                    interceptions:
                      type: number
                      format: float
                      nullable: true
                    fouls_committed:
                      type: number
                      format: float
                      nullable: true
                    pass_success_rate:
                      type: number
                      format: float
                      nullable: true
                    shots_per_game:
                      type: number
                      format: float
                      nullable: true
                    dribbles_per_game:
                      type: number
                      format: float
                      nullable: true
                    rating:
                      type: number
                      format: float
                      nullable: true

  /match-results/:
    get:
      summary: Get Match Results
      description: Returns a list of match results.
      parameters:
        - name: country
          in: query
          required: false
          schema:
            type: integer
          description: Filter matches by country ID
        - name: home_team
          in: query
          required: false
          schema:
            type: integer
          description: Filter matches by home team ID
        - name: away_team
          in: query
          required: false
          schema:
            type: integer
          description: Filter matches by away team ID
      responses:
        '200':
          description: An array of match results.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    country:
                      type: integer
                    country_name:
                      type: string
                    home_team:
                      type: integer
                    home_team_name:
                      type: string
                    away_team:
                      type: integer
                    away_team_name:
                      type: string
                    match_date:
                      type: string
                      format: date
                    home_goals:
                      type: integer
                      nullable: true
                    away_goals:
                      type: integer
                      nullable: true
                    result:
                      type: string
                      nullable: true

  /league-standings/:
    get:
      summary: Get League Standings
      description: Returns a list of league standings.
      parameters:
        - name: country
          in: query
          required: false
          schema:
            type: integer
          description: Filter standings by country ID
        - name: team
          in: query
          required: false
          schema:
            type: integer
          description: Filter standings by team ID
      responses:
        '200':
          description: An array of league standings.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    team:
                      type: integer
                    team_name:
                      type: string
                    country:
                      type: integer
                    country_name:
                      type: string
                    position:
                      type: integer
                    played:
                      type: integer
                    won:
                      type: integer
                    drawn:
                      type: integer
                    lost:
                      type: integer
                    goals_for:
                      type: integer
                    goals_against:
                      type: integer
                    goal_difference:
                      type: integer
                    points:
                      type: integer
                    recent_form:
                      type: string
                      nullable: true