swagger.yml

swagger: "2.0"
info:
  description: "This is an API server for the data scraped from the SNC website."
  version: "1.0.0"
  title: "SNC API"
  contact:
    email: "not-an-email@example.org"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "https://snc-api.herokuapp.com/"
basePath: "/v1"
tags:
- name: "matches"
  description: "Operations about matches"
- name: "goals"
  description: "Operations about goals"
- name: "penalties"
  description: "Operations about penalties"
- name: "players"
  description: "Operations about players"
- name: "goalies"
  description: "Operations about goalies"
- name: "teams"
  description: "Operations about teams"
schemes:
- "http"
paths:
  /matches:
    get:
      tags:
      - "matches"
      summary: "Get the current season's matches"
      operationId: "seasonMatches"
      produces:
        - "application/json"
      responses:
        200:
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Match"
    post:
      tags:
      - "matches"
      summary: "Add a new match"
      description: ""
      operationId: "addMatch"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Match object that needs to be added to the system"
        required: true
        schema:
          $ref: "#/definitions/Match"
      responses:
        405:
          description: "Invalid input"
      security:
      - apiKey: []
  /matches/{matchId}:
    get:
      tags:
      - "matches"
      summary: "Get a specific match"
      operationId: "findMatch"
      produces:
        - "application/json"
      parameters:
      - in: "path"
        name: "matchId"
        description: "ID of the match to fetch"
        required: true
        type: "integer"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Match"
        400:
          description: "Invalid ID supplied"
        404:
          description: "Match not be found"
    put:
      tags:
      - "matches"
      summary: "Update an existing match"
      description: ""
      operationId: "updateMatch"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "path"
        name: "matchId"
        description: "ID of the match to update"
        required: true
        type: "integer"
      - in: "body"
        name: "body"
        description: "Match object that needs to be updated"
        required: true
        schema:
          $ref: "#/definitions/Match"
      responses:
        400:
          description: "Invalid ID supplied"
        404:
          description: "Match not found"
        405:
          description: "Validation exception"
      security:
      - apiKey: []
  /matches/{matchId}/summary:
    get:
      tags:
      - "matches"
      summary: "Get a specific match"
      operationId: "matchSummary"
      produces:
        - "application/json"
      parameters:
      - in: "path"
        name: "matchId"
        description: "ID of the match to fetch"
        required: true
        type: "integer"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/MatchSummary"
        400:
          description: "Invalid ID supplied"
        404:
          description: "Match not be found"
    put:
      tags:
      - "matches"
      summary: "Update the match summary"
      description: "Used to update a match's summary. There is no POST because summaries are automatically generated when a match is created"
      operationId: "saveMatchSummary"
      consumes:
      - "application/json"
      parameters:
      - in: "path"
        name: "matchId"
        description: "ID of the match to fetch"
        required: true
        type: "integer"
      - in: "body"
        name: "body"
        description: "Match summary that needs to be saved"
        required: true
        schema:
          $ref: "#/definitions/MatchSummary"
      responses:
        200:
          description: "successful operation"
        400:
          description: "Invalid ID supplied"
        404:
          description: "Match not be found"
      security:
      - apiKey: []
  /matches/team/{teamName}:
    get:
      tags:
      - "matches"
      summary: "Find this season's schedule for a given team"
      operationId: "findTeamSchedule"
      produces:
      - "application/json"
      parameters:
      - name: "teamName"
        in: "path"
        description: "Name of the team whose schedule should be fetched"
        required: true
        type: "integer"
      responses:
        200:
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Match"
        400:
          description: "Invalid team name"
  /goals:
    get:
      tags:
      - "goals"
      summary: "All goals for the season"
      operationId: "goals"
      produces:
      - "application/json"
      parameters: []
      responses:
        200:
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Goal"
    post:
      tags:
      - "goals"
      summary: "Save a goal"
      operationId: "saveGoal"
      consumes:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "The goal to save"
        required: true
        schema:
          $ref: "#/definitions/Goal"
      responses:
        200:
          description: "successful operation"
        400:
          description: "Invalid goal"
      security:
      -  apiKey: []
  /penalties:
    get:
        tags:
        - "penalties"
        summary: "All penalties for the season"
        operationId: "penalties"
        produces:
        - "application/json"
        parameters: []
        responses:
          200:
            description: "successful operation"
            schema:
              type: "array"
              items:
                $ref: "#/definitions/Penalty"
    post:
      tags:
      - "penalties"
      summary: "Save a penalty"
      operationId: "savePenalty"
      consumes:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "The penalty to save"
        required: true
        schema:
          $ref: "#/definitions/Penalty"
      responses:
        200:
          description: "successful operation"
        400:
          description: "Invalid penalty"
      security:
      -  apiKey: []
  /players:
    get:
      tags:
      - "players"
      summary: "All players league wide"
      operationId: "players"
      produces:
      - "application/json"
      parameters: []
      responses:
        200:
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Player"
    post:
      tags:
      - "players"
      summary: "Save a player"
      operationId: "savePlayer"
      consumes:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "The player to save"
        required: true
        schema:
          $ref: "#/definitions/Player"
      responses:
        200:
          description: "successful operation"
        400:
          description: "Invalid player"
      security:
      -  apiKey: []
  /goalies:
    get:
      tags:
      - "goalies"
      summary: "All goalies league wide"
      operationId: "goalies"
      produces:
      - "application/json"
      parameters: []
      responses:
        200:
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Goalie"
    post:
      tags:
      - "goalies"
      summary: "Save a goalie"
      operationId: "saveGoalie"
      consumes:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "The goalie to save"
        required: true
        schema:
          $ref: "#/definitions/Goalie"
      responses:
        200:
          description: "successful operation"
        400:
          description: "Invalid goalie"
      security:
      -  apiKey: []
  /teams:
    get:
      tags:
      - "teams"
      summary: "Get all teams"
      operationId: "teams"
      produces:
      - "application/json"
      responses:
        200:
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Team"
        404:
          description: "Team not found"
    post:
      tags:
      - "teams"
      summary: "Create team"
      description: "Create a new team"
      operationId: "createTeam"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "The name to create"
        required: true
        schema:
          $ref: "#/definitions/Team"
      responses:
        200:
          description: "successful operation"
        400:
          description: "Invalid team supplied"
  /teams/{teamName}:
    get:
      tags:
      - "teams"
      summary: "Get team by name"
      description: ""
      operationId: "getTeamByName"
      produces:
      - "application/json"
      parameters:
      - name: "teamName"
        in: "path"
        description: "The name that needs to be fetched."
        required: true
        type: "string"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Team"
        400:
          description: "Invalid team supplied"
        404:
          description: "Team not found"
    put:
      tags:
      - "teams"
      summary: "Updated team"
      description: "This can only be done by the logged in user."
      operationId: "updateTeam"
      produces:
      - "application/json"
      parameters:
      - name: "teamName"
        in: "path"
        description: "Team that need to be updated"
        required: true
        type: "string"
      - in: "body"
        name: "body"
        description: "Updated team object"
        required: true
        schema:
          $ref: "#/definitions/Team"
      responses:
        400:
          description: "Invalid team supplied"
        404:
          description: "Team not found"
securityDefinitions:
  apiKey:
    type: "apiKey"
    in: "header"
    name: "X-API-KEY"
definitions:
  Score:
    type: "object"
    required:
      - score
      - team
    properties:
      score:
        type: "number"
        format: "int32"
      team:
        type: "string"
        description: "Which team to update, home or away"
        enum:
          - "home"
          - "away"
  Goalie:
    type: "object"
    required:
      - number
      - name
      - team
    properties:
      id:
        type: "integer"
        format: "int64"
      number:
        type: "integer"
        format: "int32"
        description: "The player's jersey number"
      name:
        type: "string"
      team:
        $ref: "#/definitions/Team"
      shots:
        type: "number"
        format: "int32"
        description: "Number of shots faced"
      saves:
        type: "number"
        format: "int32"
        description: "Number of saves made"
  Player:
    type: "object"
    required:
      - number
      - name
      - team
    properties:
      id:
        type: "integer"
        format: "int64"
      number:
        type: "integer"
        format: "int32"
        description: "The player's jersey number"
      name:
        type: "string"
      team:
        $ref: "#/definitions/Team"
      position:
        type: "string"
        enum:
          - "F"
          - "D"
  Goal:
    type: "object"
    required:
    - "type"
    - "team"
    - "period"
    - "time"
    - "scorer"
    properties:
      id:
        type: "integer"
        format: "int64"
      type:
        type: "string"
        enum:
        - "RG"
        - "PP"
        - "SH"
      team:
        $ref: "#/definitions/Team" # consider just using the ID instead
      period:
        type: "integer"
        format: "int32"
        description: "The period the goal was scored during"
      time:
        type: "integer"
        format: "int32"
        description: "Seconds left in the period when the goal was scored"
      scorer:
        type: "string"
      assists:
        type: "array"
        items:
          type: "string"
  Penalty:
    type: "object"
    required:
      - period
      - team
      - time
      - offense
      - offender
    properties:
      period:
        type: "integer"
        format: "int32"
      team:
        $ref: "#/definitions/Team"
      time:
        type: "integer"
        format: "int32"
        description: "Seconds left in the period when the penalty was incurred"
      offense:
        type: "string"
        description: "Title of the penalty"
        example: "Hooking"
      offender:
        type: "string"
      pim:
        type: "integer"
        format: "int32"
        description: "Penalty infraction minutes"
        example: 2
  Team:
    type: "object"
    required:
    - "name"
    - "division"
    - "logoUrl"
    properties:
      id:
        type: "integer"
        format: "int64"
      name:
        type: "string"
        example: "Bears"
      logoUrl:
        type: "string"
        example: "http://www.aucklandsnchockey.com/media/leagues/5788/graphics/bears_ice_hockey_team_official_logo.jpg"
      division:
        type: "string"
        example: "C"
      players:
        type: "array"
        items:
          $ref: "#/definitions/Player"
  Match:
    type: "object"
    required:
      - start
      - away
      - home
      - rink
    properties:
      start:
        type: "string"
        format: "date"
        description: "Date time at which the match starts, in UTC"
      season:
        type: "integer"
        format: "int32"
        description: "Season in which the match was/will be played. Usually the year"
        example: 2017
      away:
        $ref: "#/definitions/Team"
      home:
        $ref: "#/definitions/Team"
      awayScore:
        type: "integer"
        format: "int32"
      homeScore:
        type: "integer"
        format: "int32"
      rink:
        type: "string"
  MatchSummary:
    type: "object"
    required:
      - start
      - away
      - home
      - rink
    properties:
      start:
        type: "string"
        format: "date"
        description: "Date time at which the match starts, in UTC"
      away:
        $ref: "#/definitions/Team"
      home:
        $ref: "#/definitions/Team"
      awayScore:
        type: "integer"
        format: "int32"
      homeScore:
        type: "integer"
        format: "int32"
      rink:
        type: "string"
      goals:
        description: "Goals indexed by team name"
        additionalProperties:
          type: "array"
          items:
            $ref: "#/definitions/Goal"
      shots:
        description: "TODO"
      powerPlays:
        description: "TODO"
      penalities:
        description: "Penalties indexed by team name"
        additionalProperties:
          type: "array"
          items:
            $ref: "#/definitions/Penalty"
      players:
        description: "Players indexed by team name"
        additionalProperties:
          type: "array"
          items:
            $ref: "#/definitions/Player"
      goalies:
        description: "Goalies indexed by team name"
        additionalProperties:
          type: "array"
          items:
            $ref: "#/definitions/Goalie"