Second Swagger API Document With Schema

[godtaehee]

# Every Open API file needs this
swagger: '2.0'

# Document metadata
info:
  version: "0.3.0"
  title: Music API

# URL data
host: api.muzicplayz.com
basePath: /v3
schemes:
  - https

# Endpoints
paths:
  # Retrieve information on one or more playlists
  /playlist:
    # Get one or more playlists
    get:
      # Query parameters
      parameters:
        # limit
        - name: limit
          in: query
          required: false
          type: integer
          description: Number of playlists to return

        # offset
        - name: offset
          in: query
          required: false
          type: integer
          description: Index of the first playlist to return (0=start at the begining, 10 = skip the first 10, etc)

        # search
        - name: search
          in: query
          required: false
          type: string
          description: Return playlists whose name contains this string

      # Responses
      responses:
        # Response code
        200:
          description: Successful response

    # Create a new playlist
    post:
      # Query parameters
      parameters:
        - name: newPlaylist
          in: body
          required: true
          schema:
            $ref: '#/definitions/newPlaylist'

      # Responses
      responses:
        # Response code
        200:
          description: Successful response

  /playlist/{playlist-id}:
    # Delete a playlist
    delete:
      # Path parameters
      parameters:
        # playlist-id
        - name: playlist-id
          in: path
          required: true
          type: string
          description: ID is a string because it contains both text and numbers.

      # Responses
      responses:
        # Response code
        200:
          description: Successful response

    get:
      # Path parameters
      parameters:
        # playlist-id
        - name: playlist-id
          in: path
          required: true
          type: string
          description: ID is a string because it contains both text and numbers.
      # Responses
      responses:
        # Response code
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/playlistWithSongs'

# Schema definitions
definitions:
  # newPlaylist
  newPlaylist:
    properties:
      name:
        type: string
      songIds:
        type: array
        items:
          type: integer
    required:
      - name

  # playlistWithSongs
  playlistWithSongs:
    properties:
      id:
        type: integer
      name:
        type: string
      songs:
        type: array
        items:
          $ref: '#/definitions/song'

  # song
  song:
    properties:
      id:
        type: integer
      title:
        type: string
      artist:
        type: string