openapi.yaml

openapi: 3.0.3
info:
  title: Fantasy Football
  description: API Specificaion for Fantasy Football in English Premier Leage (EPL)
  version: 1.0.0
  contact:
    name: Vinodh Kumar
    email: vinodh5052@gmail.com
    url: https://github.com/vinodh-thimmisetty
  license:
    name: Open Source
    url: https://apache.org
  termsOfService: /terms-of-service
servers:
  - url: '{protocol}://{dns}:{port}/{version}'
    description: Sever Configuration
    variables:
      protocol:
        enum:
          - http
          - https
        default: http
      dns:
        enum:
          - 'localhost'
          - 'api.stage'
          - 'api.test'
          - 'api.prod'
        default: 'localhost'
      port:
        enum:
          - '8080'
          - '8443'
        default: '8080'
      version:
        enum:
          - 'v1'
          - 'v2'
        default: 'v1'
externalDocs:
  url: /githb-wiki-page
  description: Api Documentaion WIKI in GITHUB
security:
  - BasicAuth: []
  - BearerAuth: []
  - ApiKeyAuth: []
  - CookieAuth: []
  - OpenIdAuth: []
  - OAuth2:
      - read
      - write
tags:
  - name: FPL
    description: Fantasy Premier League
paths:
  /teams:
    get:
      summary: Returns a list of Teams available in EPL
      description: Every team will have details like Name, City, Jersey Colors etc.
      operationId: getAllTeams
      tags:
        - FPL
      security: []   # No security
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/reqestHeader'
      responses:
        200:
          description: List of Teams
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Team'
                example:
                  - id: 1
                    name: Liverpool
                    city: Liverpool
                    code: LFC
                  - id: 2
                    name: Tottenhum Hotspur
                    city: London
                    code: Spurs
        401:
          $ref: '#/components/responses/UnAuthorized'
        404:
          $ref: '#/components/responses/NotFound'
        5XX:
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/GenericError'
    post:
      summary: Add a New Team into EPL
      description: Every Year promoted teams will be added to EPL
      operationId: createTeam
      security:
        - OAuth2: [admin]
      tags:
        - FPL
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Team'
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                payload:
                  $ref: '#/components/schemas/Team'
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
          links:
            GetTeamById:
              $ref: '#/components/links/GetTeamById'
        401:
          $ref: '#/components/responses/UnAuthorized'
        404:
          $ref: '#/components/responses/NotFound'
        403:
          $ref: '#/components/responses/AccessForbidden'
        5XX:
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/GenericError'
  /teams/{teamId}:
    get:
      summary: Returns a Team by ID
      description: Every team will have details like Name, City, Code etc.
      operationId: getTeamById
      tags:
        - FPL
      parameters:
        - $ref: '#/components/parameters/teamId'
        - $ref: '#/components/parameters/reqestHeader'
      responses:
        200:
          description: Particular Team Information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        401:
          $ref: '#/components/responses/UnAuthorized'
        404:
          $ref: '#/components/responses/NotFound'
        5XX:
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/GenericError'
    put:
      summary: Update Team Information by ID
      description: Every Year, new Color Jersey might be added to Teams Kit
      operationId: updateTeam
      tags:
        - FPL
      parameters:
        - $ref: '#/components/parameters/teamId'
        - $ref: '#/components/parameters/reqestHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Team'
      responses:
        202:
          description: Updated Particular Team Information
        401:
          $ref: '#/components/responses/UnAuthorized'
        404:
          $ref: '#/components/responses/NotFound'
        5XX:
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/GenericError'
    delete:
      description: Remove Team
      summary: Remove relegated Teams from EPL
      operationId: removeTeam
      tags:
        - FPL
      parameters:
        - $ref: '#/components/parameters/teamId'
        - $ref: '#/components/parameters/reqestHeader'
      responses:
        204:
          description: Removed Particular Team Information
        401:
          $ref: '#/components/responses/UnAuthorized'
        404:
          $ref: '#/components/responses/NotFound'
        5XX:
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/GenericError'
  /teams/{teamId}/{position}:
    get:
      summary: Returns List of Player Names
      description: Returns List of Players Playing in the particular position for a Team
      operationId: getPlayersByTeamAndByPosition
      tags:
        - FPL
      parameters:
        - $ref: '#/components/parameters/teamId'
        - $ref: '#/components/parameters/reqestHeader'
        - in: path
          name: position
          schema:
            type: string
            enum:
              - GK
              - DEF
              - CB
              - LB
              - RB
              - MID
              - CDM
              - CAM
              - LM
              - RM
              - ST
              - RW
              - LW
              - CF
          example: GK
          required: true
      responses:
        200:
          description: List of Player Names
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Player'
        401:
          $ref: '#/components/responses/UnAuthorized'
        404:
          $ref: '#/components/responses/NotFound'
        5XX:
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/GenericError'
  /teams/{playerId}:
    get:
      summary: Get Player Information
      description: Get All available EPL Player details
      operationId: getTeamsByPlayerId
      tags:
        - FPL
      parameters:
        - $ref: '#/components/parameters/playerId'
        - $ref: '#/components/parameters/reqestHeader'
      responses:
        200:
          description: List of Player Names
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Player'
        401:
          $ref: '#/components/responses/UnAuthorized'
        404:
          $ref: '#/components/responses/NotFound'
        5XX:
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/GenericError'
  /teams/{playerId}/change_profile_pic:
    post:
      summary: Update Player Profile PIC
      description: Update Player Profile PIC
      operationId: updatePlayerProfilePic
      tags:
        - FPL
      parameters:
        - $ref: '#/components/parameters/playerId'
        - $ref: '#/components/parameters/reqestHeader'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                filename:
                  type: string
                  format: binary
      responses:
        202:
          description: Changed Profile pic
        401:
          $ref: '#/components/responses/UnAuthorized'
        404:
          $ref: '#/components/responses/NotFound'
        5XX:
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/GenericError'
components:
  parameters:
    limit:
      in: query
      name: limit
      required: false
      schema:
        type: integer
        default: 15
    offset:
      in: query
      name: offset
      required: false
      schema:
        type: integer
        default: 0
    reqestHeader:
      in: header
      name: X-Request-ID
      required: true
      schema:
        type: string
        format: uuid
    teamId:
      name: teamId
      in: path
      required: true
      schema:
        type: integer
        readOnly: true
        minimum: 1
        pattern: '^[0-9]+$'
        nullable: false
    playerId:
      in: path
      name: playerId
      schema:
        type: integer
        readOnly: true
        minimum: 1
        nullable: false
      required: true
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            oneOf:
              - type: string
              - $ref: '#/components/schemas/ApiError'
    UnAuthorized:
      description: Un-Authorized
      headers:
        WWW_Authenticate:
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    AccessForbidden:
      description: Forbidden Access
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    NotFound:
      description: Not-Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ServerError:
      description: Server-Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    GenericError:
      description: Default Response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  schemas:
    Team:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        city:
          type: string
        code:
          type: string
        players:
          type: array
          items:
            $ref: '#/components/schemas/Player'
      required:
        - name
        - city
    Player:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        position:
          type: string
        country:
          type: string
      required:
        - name
    ApiError:
      type: object
      properties:
        code: # HTTP Status Code
          type: integer
          default: -1
        message:
          type: string
      required:
        - code
        - message
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic # Authorization: Basic abcdef12345==
    BearerAuth:
      type: http
      scheme: bearer # Authorization: Bearer abcdef12345==
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY # X-API-Key: abcdef12345
    CookieAuth:
      type: apiKey
      in: cookie
      name: JSESSIONID #JSESSIONID=abcde12345; Path=/; HttpOnly
    OpenIdAuth:
      type: openIdConnect
      openIdConnectUrl: /openid.auth
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes:
            read: Read Profile
            write: Write Access
            admin: Admin Access
          refreshUrl: /oauth/refresh
        implicit:
         authorizationUrl:  /oauth/authorize
         scopes:
           read: Read Profile
         refreshUrl: /oauth/refresh
        clientCredentials:
          tokenUrl: /oauth/authorize
          scopes: {}
          refreshUrl: /oauth/refresh
        password:
          tokenUrl:  /oauth/authorize
          scopes:
            read: Read Profile
          refreshUrl: /oauth/refresh
  links:
    GetTeamById:
      # operationId: getTeamById
      # or
      operationRef: '#/paths/~1teams~1{teamId}/get'
      parameters:
        userId: '$response.body#/id'