Add API Documentation

README.md

@@ -19,6 +19,8 @@ gem "versafleet"
 
 To access the API, you'll need to create a `Versafleet::Client` and pass in your API Key and Secret Key. See [How to obtain API keys](https://versafleet.docs.apiary.io/#introduction/to-obtain-api-keys-(please-keep-them-safe!))
 
+Need more details? See [VersaFleet API Documentation](https://rubydoc.info/gems/versafleet) to see how it works internally.
+
 ```ruby
 client = Versafleet::Client.new(client_id: ENV["CLIENT_ID"], client_secret: ENV["CLIENT_SECRET"])
 ```
@@ -62,7 +64,7 @@ client.tasks.create(task_attributes: {})
 # assign task to driver
 client.tasks.assign(task_id: task_id, task: {driver_id: driver_id, vehicle_id: vehicle_id, remarks: "Notes"})
 # assign multiple tasks to driver
-client.tasks.assign_multiple(task: {ids: [], driver_id: driver_id, vehicle_id: vehicle_id, remarks: "Notes")
+client.tasks.assign_multiple(task: {ids: [], driver_id: driver_id, vehicle_id: vehicle_id, remarks: "Notes"})
 # unassign task
 client.tasks.unassign(task_id: task_id)
 # unassign multiple tasks

lib/versafleet/client.rb

@@ -1,26 +1,53 @@
 module Versafleet
   class Client
+    # Default API endpoint
     BASE_URL = "https://api.versafleet.co/api"
 
-    attr_reader :client_id, :client_secret
+    # @return [String] Gets the VersaFleet API Key
+    attr_reader :client_id
 
+    # @return [String] Gets the VersaFleet Secret Key
+    attr_reader :client_secret
+
+    # Initialize a new VersaFlet client
+    #
+    # == Example:
+    #
+    #   client = Versafleet::Client.new(client_id: ENV["CLIENT_ID"], client_secret: ENV["CLIENT_SECRET"])
+    #   # use Jobs resource
+    #   client.jobs.list
+    #
+    # @param client_id [String] VersaFleet API Key
+    # @param client_secret [String] VersaFleet Secret Key
     def initialize(client_id:, client_secret:)
       @client_id = client_id
       @client_secret = client_secret
     end
 
+    # Jobs Resource instance
+    #
+    # @return [JobsResource]
     def jobs
       JobsResource.new(self)
     end
 
+    # Tasks Resource instance
+    #
+    # @return [TasksResource]
     def tasks
       TasksResource.new(self)
     end
 
+    # Drivers Resource instance
+    #
+    # @return [DriversResource]
     def drivers
       DriversResource.new(self)
     end
 
+    # Initializes a new Faraday connection
+    #
+    # @return [Faraday::Connection]
     def connection
       @connection ||= Faraday.new(params: default_params) do |conn|
         conn.url_prefix = BASE_URL

lib/versafleet/resources/drivers.rb

@@ -1,19 +1,64 @@
 module Versafleet
   class DriversResource < Resource
+    # List All Drivers
+    #
+    # == Examples:
+    #
+    #   client.drivers.list
+    #   # set per page to 20
+    #   client.drivers.list(per_page: 20)
+    #   # move to page 2
+    #   client.drivers.list(page: 2, per_page: 20)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/drivers-api/list-all-drivers VersaFleet API}
+    #
+    # @param params [Hash] the filter query
+    # @return [Collection]
     def list(**params)
       response = get_request("drivers", params: params)
       Collection.from_response(response, key: "drivers", type: Driver)
     end
 
+    # Get Driver details
+    #
+    # == Examples:
+    #
+    #   client.drivers.retrieve(driver_id: 123)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/drivers-api/show-a-driver VersaFleet API}
+    #
+    # @param driver_id [Integer] Driver ID
+    # @return [Driver]
     def retrieve(driver_id:)
       Driver.new get_request("drivers/#{driver_id}").body.dig("driver")
     end
 
+    # Create a Driver
+    #
+    # == Examples:
+    #
+    #   client.drivers.create(driver: {name: "Yolo", dob: "1990-09-09"})
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/drivers-api/create-a-driver VersaFleet API}
+    #
+    # @param driver [Hash] Driver request payload
+    # @return [Driver]
     def create(driver:)
       payload = {driver: driver}
       Driver.new post_request("drivers", body: payload).body.dig("driver")
     end
 
+    # Update Driver
+    #
+    # == Examples:
+    #
+    #   client.drivers.update(driver_id: 123, driver: {name: "John"})
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/drivers-api/update-a-driver VersaFleet API}
+    #
+    # @param driver_id [Integer] Driver ID
+    # @param driver [Hash] Driver request payload
+    # @return [Driver]
     def update(driver_id:, driver:)
       payload = {driver: driver}
       Driver.new put_request("drivers/#{driver_id}", body: payload).body.dig("driver")

lib/versafleet/resources/jobs.rb

@@ -1,26 +1,95 @@
 module Versafleet
   class JobsResource < Resource
+    # List All Jobs
+    #
+    # == Examples:
+    #
+    #   client.jobs.list
+    #   # set per page to 20
+    #   client.jobs.list(per_page: 20)
+    #   # move to page 2
+    #   client.jobs.list(page: 2, per_page: 20)
+    #   # filter by Customer ID
+    #   client.jobs.list(customer_id: 1231)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/jobs-v2-api/list-all-jobs VersaFleet API}
+    #
+    # @param params [Hash] the filter query
+    # @return [Collection]
     def list(**params)
       response = get_request("v2/jobs", params: params)
       Collection.from_response(response, key: "jobs", type: Job)
     end
 
+    # Create a Job
+    #
+    # == Examples:
+    #
+    #   # see the VersaFleet API for the request body reference
+    #   client.jobs.create(job: {})
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/jobs-v2-api/create-a-new-job VersaFleet API}
+    #
+    # @param attributes [Hash] Request body
+    # @return [Job]
     def create(**attributes)
       Job.new post_request("v2/jobs", body: attributes).body.dig("job")
     end
 
+    # Update Job
+    #
+    # == Examples:
+    #
+    #   # see the VersaFleet API for the request body reference
+    #   client.jobs.update(job_id: 123, job: {})
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/jobs-v2-api/update-job-or-base-task-details VersaFleet API}
+    #
+    # @param job_id [Integer] Job ID
+    # @param attributes [Hash] Request body
+    # @return [Job]
     def update(job_id:, **attributes)
       Job.new put_request("v2/jobs/#{job_id}", body: attributes).body.dig("job")
     end
 
+    # Get Job details
+    #
+    # == Examples:
+    #
+    #   client.jobs.retrieve(job_id: 123)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/jobs-v2-api/view-details-of-a-job VersaFleet API}
+    #
+    # @param job_id [Integer] Job ID
+    # @return [Job]
     def retrieve(job_id:)
       Job.new get_request("v2/jobs/#{job_id}").body.dig("job")
     end
 
+    # Cancel a Job
+    #
+    # == Examples:
+    #
+    #   client.jobs.cancel(job_id: 123)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/jobs-v2-api/cancel-a-job VersaFleet API}
+    #
+    # @param job_id [Integer] Job ID
     def cancel(job_id:)
+      # TODO: Remove Job object return
       Job.new put_request("v2/jobs/#{job_id}/cancel", body: {}).body
     end
 
+    # List Tasks of Job
+    #
+    # == Examples:
+    #
+    #   client.jobs.list_tasks(job_id: 123)
+    #
+    # {https://versafleet.docs.apiary.io/#reference/0/jobs-v2-api/list-tasks-of-job VersaFleet API}
+    #
+    # @param job_id [Integer] Job ID
+    # @return [Collection]
     def list_tasks(job_id:)
       response = get_request("v2/jobs/#{job_id}/tasks")
       Collection.from_response(response, key: "tasks", type: Task)