swagger.yaml

openapi: 3.0.0
servers:
  - description: GiTils API
    url: https://gitils.giesela.io
info:
  description: API specification for GiTils.
  version: "0.0.1"
  title: GiTils 
  contact:
    email: team@giesela.io
  license:
    name: MIT
    url: 'https://cdn.rawgit.com/GieselaDev/GiTils/4e530e8d/LICENSE'
    
paths:
  /lyrics/{query}:
    get:
      summary: Attempts return of the specified lyrics for the query.
      parameters:
        - name: query
          in: path
          required: true
          description: Query to search through LyricsFinder
          schema:
            type : string
      responses:
       '200':
        description: Lyric success or Lyric error
        content:
          application/json:
             schema:
               oneOf:
                 - $ref: '#/components/schemas/LyricSuccess'
                 - $ref: '#/components/schemas/LyricError'
        examples:
          success:    
              artist: Artist
              lyrics: "[Verse]\nLyrics\n[Chorus]\nLyrics"
              origin:
                query: lookup string
                source_name:  Name
                url: https://lyric.url
              release_date: 1520121600
              success: true
              timestamp: 1530840488.4070156
              title: Title
          error:
            error: Couldn't find lyrics for query (query)
            success: false
       '429':
        description: HTTP Too Many Requests
       '5XX':
        description: Unexpected error  
        
  /tokens/spotify:
   get:
      summary: Return valid spotify token.
      responses:
       '200':
         description: Spotify Access Token
         content:
          application/json:
              schema:
                $ref: '#/components/schemas/SpotifyAPI'
       '429':
        description: HTTP Too Many Requests
       '5XX':
         description: Unexpected error
         
components:
  schemas:
    LyricSuccess:
      properties:
        artist: 
          type: string
          description: Artist, if any, of the provided lyric.
        lyrics:
          type: string
          description: Newline-separated lyrics string.
        origin: 
          type: object
          properties:
            query:
              type: string
              description: Origin query string searched through LyricsFinder.
            source_name:
              type: string
              description: The provider/source of the lyrics.
            url: 
              type: string
              description: The source URL to the lyrics webpage.
        release_date:
          type: integer
          description: The release date (if any) of the provided lyric as a UNIX timestamp.
        success:
          type: boolean
          enum:
            - true
        timestamp:
          type: integer
          description: The timestamp of the query string lookup to LyricsFinder.
        title:
          type: string
          description: The title of the provided lyric.
    LyricError:
      properties:
        error:
          type: string
          description: Error message - could not find lyrics for provided query string.
        success:
          type: boolean
          enum:
            - false
    SpotifyAPI:
      properties:
        access_token:
          type: string
          description: An access token that can be provided in subsequent calls, for example to Spotify Web API services.
        expires_at:
          type: integer
          description: The time (represented as a UNIX timestamp) for which the access token expires at.
        expires_in: 
          type: integer
          description: The time period (in seconds) for which the access token is valid.
        scope:
          type: string
          description: A space-separated list of scopes which have been granted for this access_token.
        token_type: 
          type: string
          description: How access token can be utilized, always Bearer.