onsi 0.8.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 96d2e299515f7829ffc2f93f76dfc26cbe8a25de
-  data.tar.gz: 67855153d40ba6e49e46d0d2e87af9f9ef587987
+  metadata.gz: 4603a96ecc939b0121b0ba15b31f09fb54f6078c
+  data.tar.gz: 0b12f9fead4d425b6a64555d10214d8ea2f5d7aa
 SHA512:
-  metadata.gz: 62ee8543afa30b562aad29d3ed678ab47f930b03761f3cd01c7f6e76cb68aba37f8317df61dfaae4004125aac164813dcf02e74a90788e67ce01780e952d3407
-  data.tar.gz: a8a4a5be644d66942fc3fb362e9692fec191c1fca43e1b1202d1678326e66da44e2d3616bcf0e4c8d582aac65788e37cc45b626b9017ebb4ff7ecba788fb5396
+  metadata.gz: 738ea3ac8f9fc4fc118130c9b9760c66a1ca49d3bc5c6efd0870d7f052f6f578383cb357439e1084aa9cbc8675f172f322c291540b58f9b3239a2a367ae4dba1
+  data.tar.gz: fa8db433e03643c00579eb51f0d3d8c0e186ccee4aec830563aa014358d53142b87a03b5ab287e01ea2de310ffd03a8eed5f3b29c5bf8432102937053a664d49

data/.circleci/config.yml

@@ -2,7 +2,7 @@ version: 2
 jobs:
   latest:
     environment:
-      CC_TEST_REPORTER_ID: 15f1ab72e4d38e92cc8ffe4490022ae9bdc9265a0319c30e673ee3e4e7a5a371
+      CC_TEST_REPORTER_ID: 7e6c6740d17509f50ec9c750311962b3b3fcb2d3a7033c2f664dc3b012bd9439
     docker:
       - image: circleci/ruby:latest
     working_directory: ~/repo

data/.codeclimate.yml

@@ -4,4 +4,4 @@ engines:
   rubocop:
     enabled: true
   bundler-audit:
-    enabled: true
+    enabled: false

data/.yardopts

@@ -0,0 +1,4 @@
+--no-private
+lib/**/*.rb
+README
+CHANGELOG

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Version 1.0.0
+
+## Released November 15, 2018
+
+### Changes
+
+- The first official release of Onsi.
+
+### Upgrading
+
+- There are no breaking changes from 0.8.0 to 1.0.0

data/README.md

@@ -4,11 +4,11 @@ Used to generate API responses from a Rails App.
 
 ***
 
-[![CircleCI](https://circleci.com/gh/skylarsch/onsi.svg?style=svg)](https://circleci.com/gh/skylarsch/onsi)
+[![CircleCI](https://circleci.com/gh/maddiesch/onsi.svg?style=svg)](https://circleci.com/gh/maddiesch/onsi)
 
-[![Maintainability](https://api.codeclimate.com/v1/badges/c3ee44371f7565f2709c/maintainability)](https://codeclimate.com/github/skylarsch/onsi/maintainability)
+[![Maintainability](https://api.codeclimate.com/v1/badges/8d21ec50b172146416c9/maintainability)](https://codeclimate.com/github/maddiesch/onsi/maintainability)
 
-[![Test Coverage](https://api.codeclimate.com/v1/badges/c3ee44371f7565f2709c/test_coverage)](https://codeclimate.com/github/skylarsch/onsi/test_coverage)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/8d21ec50b172146416c9/test_coverage)](https://codeclimate.com/github/maddiesch/onsi/test_coverage)
 
 ### Install
 

data/Rakefile

@@ -1,6 +1,19 @@
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'yard'
 
 RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec
+
+namespace :docs do
+  desc 'Generate docs'
+  task :generate do
+    YARD::CLI::Yardoc.run
+  end
+
+  desc 'Get docs stats'
+  task :stats do
+    YARD::CLI::Stats.run('--list-undoc')
+  end
+end

data/lib/onsi.rb

@@ -7,5 +7,7 @@ require 'onsi/params'
 require 'onsi/resource'
 require 'onsi/version'
 
+##
+# Create versioned JSON-API objects.
 module Onsi
 end

data/lib/onsi/controller.rb

@@ -1,20 +1,53 @@
 require 'active_support/concern'
 
 module Onsi
+  ##
+  # Helper methods for rendering API responses.
+  #
+  # @example
+  #   class PersonController < ActionController::API
+  #     include Onsi::Controller
+  #
+  #     render_version(:v1)
+  #
+  #     def show
+  #       person = Person.find(params[:id])
+  #       render_resource(person)
+  #     end
+  #   end
   module Controller
     extend ActiveSupport::Concern
 
+    ##
+    # Defines class methods available on the class.
     module ClassMethods
+      ##
+      # Set a controller wide default render version.
+      #
+      # @param version [Symbol] The version.
       def render_version(version = nil)
         @render_version = version if version
         @render_version
       end
 
+      ##
+      # Ensures that the render_version is set on a subclass
+      #
+      # @private
       def inherited(subclass)
         subclass.render_version(@render_version)
       end
     end
 
+    ##
+    # Render the JSON response.
+    #
+    # @param resource [Onsi::Resource, Enumerable, Onsi::Model]
+    #
+    # @param opts [Hash] The options hash. If a version is included that will
+    #   take presidence over the controller default .render_version
+    #
+    #   - The other keys for opts will be passed directly the #render method.
     def render_resource(resource, opts = {})
       version = opts.delete(:version) || self.class.render_version || Model::DEFAULT_API_VERSION
       payload = Resource.render(resource, version)

data/lib/onsi/error_responder.rb

@@ -3,6 +3,25 @@ require 'active_support/concern'
 module Onsi
   ##
   # Handles default errors without StandardError
+  #
+  # Error handled by default:
+  # - ActiveRecord::RecordNotFound
+  # - ActiveRecord::RecordInvalid
+  # - ActionController::ParameterMissing
+  # - {Onsi::Params::MissingReqiredAttribute}
+  # - {Onsi::Params::RelationshipNotFound}
+  # - {Onsi::Errors::UnknownVersionError}
+  #
+  # @example
+  #   class PeopleController < ApplicationController
+  #     include Onsi::Controller
+  #     include Onsi::ErrorResponderBase
+  #
+  #     # ...
+  #   end
+  #
+  # @author Maddie Schipper
+  # @since 1.0.0
   module ErrorResponderBase
     extend ActiveSupport::Concern
 
@@ -15,16 +34,45 @@ module Onsi
       rescue_from Onsi::Errors::UnknownVersionError,     with: :respond_invalid_version_error_400
     end
 
+    ##
+    # Render an API error response.
+    #
+    # @param response [Onsi::ErrorResponse] The response object to render
     def render_error(response)
       render(response.renderable)
     end
 
+    ##
+    # Can be overriden to report an un-handled exception to your error service
+    # of choice.
+    #
+    # @param exception [StandardError] The error to report.
+    #
+    # @example
+    #   class ApplicationController < ActionController::API
+    #     include Onsi::ErrorResponderBase
+    #     include Onsi::Controller
+    #
+    #     def notify_unhandled_exception(exception)
+    #       Bugsnag.notify(exception)
+    #     end
+    #
+    #     # ...
+    #   end
+    def notify_unhandled_exception(exception)
+      Rails.logger.error "Unhandled Exception `#{exception.class.name}: #{exception.message}`"
+    end
+
+    ##
+    # @private
     def render_error_404(_error)
       response = ErrorResponse.new(404)
       response.add(404, 'not_found')
       render_error(response)
     end
 
+    ##
+    # @private
     def render_error_422(error)
       response = ErrorResponse.new(422)
       error.record.errors.details.each do |name, details|
@@ -40,6 +88,8 @@ module Onsi
       render_error(response)
     end
 
+    ##
+    # @private
     def respond_param_error_400(error)
       response = ErrorResponse.new(400)
       response.add(
@@ -50,6 +100,8 @@ module Onsi
       render_error(response)
     end
 
+    ##
+    # @private
     def respond_missing_relationship_error_400(error)
       response = ErrorResponse.new(400)
       response.add(
@@ -60,6 +112,8 @@ module Onsi
       render_error(response)
     end
 
+    ##
+    # @private
     def respond_invalid_version_error_400(error)
       notify_unhandled_exception(error)
       response = ErrorResponse.new(400)
@@ -71,6 +125,8 @@ module Onsi
       render_error(response)
     end
 
+    ##
+    # @private
     def respond_missing_attr_error_400(error)
       response = ErrorResponse.new(400)
       response.add(
@@ -83,10 +139,6 @@ module Onsi
       render_error(response)
     end
 
-    def notify_unhandled_exception(exception)
-      Rails.logger.error "Unhandled Exception `#{exception.class.name}: #{exception.message}`"
-    end
-
     private
 
     def error_metadata(error)
@@ -103,14 +155,48 @@ module Onsi
     end
   end
 
+  ##
+  # The error response container.
+  #
+  # @author Maddie Schipper
+  # @since 1.0.0
+  #
+  # @example
+  #   def handle_error(error)
+  #     response = Onsi::ErrorResponse.new(400)
+  #     response.add(400, 'bad_request', title: 'The payload was invalid')
+  #     render_error(response)
+  #   end
   class ErrorResponse
+    ##
+    # The HTTP status for the response.
+    #
+    # @return [Integer]
     attr_reader :status
 
+    ##
+    # Create a new ErrorResponse
+    #
+    # @param status [Integer] The HTTP status for the response.
     def initialize(status)
       @status = status
       @errors = []
     end
 
+    ##
+    # Add a renderable error to the errors
+    #
+    # @param status [#to_s, nil] The status of the error. Usually the same as
+    #   the HTTP status passed to #initialize
+    #
+    # @param code [String] The error code for the error. e.g. `bad_request`
+    #
+    # @param title [String, nil] The user displayable title for the error.
+    #
+    # @param details [String, nil] The user displayable details for the error.
+    #
+    # @param meta [Hash, nil] Any additional metadata to associate
+    #   with the error.
     def add(status, code, title: nil, details: nil, meta: nil)
       @errors << {}.tap do |err|
         err[:status] = (status || @status).to_s
@@ -121,10 +207,18 @@ module Onsi
       end
     end
 
+    ##
+    # Create the error objects.
+    #
+    # @return [Hash] The JSON-API error hash.
     def as_json
       { errors: @errors.as_json }
     end
 
+    ##
+    # Returns a hash that can be passed to #render
+    #
+    # @private
     def renderable
       {
         json:   as_json,
@@ -137,6 +231,17 @@ end
 module Onsi
   ##
   # Handles default errors and builds JSON-API responses.
+  #
+  # @note Also includes Onsi::ErrorResponderBase but will add a StandardError
+  #   handler.
+  #
+  # @example
+  #   class PeopleController < ApplicationController
+  #     include Onsi::Controller
+  #     include Onsi::ErrorResponder
+  #
+  #     # ...
+  #   end
   module ErrorResponder
     extend ActiveSupport::Concern
 
@@ -145,6 +250,10 @@ module Onsi
       include(Onsi::ErrorResponderBase)
     end
 
+    ##
+    # Render a 500 error.
+    #
+    # @private
     def render_error_500(error)
       notify_unhandled_exception(error)
       response = ErrorResponse.new(500)

data/lib/onsi/errors.rb

@@ -1,18 +1,39 @@
 module Onsi
+  ##
+  # Container module for custom errors
   module Errors
+    ##
+    # Base Error for all Onsi custom errors
+    #
+    # @author Maddie Schipper
+    # @since 1.0.0
     class BaseError < StandardError; end
 
+    ##
+    # An unknown version is requested to be rendered
+    #
+    # @author Maddie Schipper
+    # @since 1.0.0
     class UnknownVersionError < BaseError
-      attr_reader :klass, :version
+      ##
+      # The class that does not support the requested version.
+      attr_reader :klass
 
+      ##
+      # The version requested that isn't supported
+      attr_reader :version
+
+      ##
+      # Create a new UnknownVersionError
+      #
+      # @param klass (see #klass)
+      #
+      # @param version (see #version)
       def initialize(klass, version)
+        super("Unsupported version #{version} for #{klass.name}")
         @klass = klass
         @version = version
       end
-
-      def message
-        "Unsupported version #{version} for #{klass.name}"
-      end
     end
   end
 end

data/lib/onsi/includes.rb

@@ -1,19 +1,64 @@
 module Onsi
+  ##
+  # Used to include other objects in a root Resource objects.
+  #
+  # @example
+  #   def index
+  #     @person = Person.find(params[:person_id])
+  #     @email = @person.emails.find(params[:id])
+  #     @includes = Onsi::Includes.new(params[:include])
+  #     @includes.fetch_person { @person }
+  #     @includes.fetch_messages { @email.messages }
+  #     render_resource(Onsi::Resource.new(@email, params[:version].to_sym, includes: @includes))
+  #   end
   class Includes
+    ##
+    # The fetch method matcher regex
+    #
+    # @private
+    FETCH_METHOD_REGEXP = Regexp.new('\Afetch_(?:.*)\z').freeze
+
+    ##
+    # The includes
+    #
+    # @return [Array<Symbol>]
     attr_reader :included
 
+    ##
+    # Create a new Includes object.
+    #
+    # @param included [String, Enumerable<String, Symbol>, nil] The keys to be
+    #   included.
+    #
+    # @return [Onsi::Includes]
     def initialize(included)
       @included = parse_included(included)
     end
 
+    ##
+    # @private
     def method_missing(name, *args, &block)
-      if name =~ /\Afetch_(.*)/
+      if name =~ FETCH_METHOD_REGEXP
         add_fetch_method(name.to_s.gsub(/\Afetch_/, ''), *args, &block)
       else
         super
       end
     end
 
+    ##
+    # @private
+    def respond_to_missing?(name, include_private = false)
+      if name =~ FETCH_METHOD_REGEXP
+        true
+      else
+        super
+      end
+    end
+
+    ##
+    # Load all included resources.
+    #
+    # @private
     def load_included
       @load_included ||= {}.tap do |root|
         included.each do |name|

data/lib/onsi/model.rb

@@ -1,16 +1,68 @@
 require 'active_support/concern'
 
 module Onsi
+  ##
+  # The Model helper for create a renderable helper.
+  #
+  # @author Maddie Schipper
+  # @since 1.0.0
+  #
+  # @example
+  #   class Person < ApplicationRecord
+  #     include Onsi::Model
+  #
+  #     api_render(:v1) do
+  #       # Passing the name of the attribute only will call that name as a method on
+  #       # the instance of the method.
+  #       attribute(:first_name)
+  #       attribute(:last_name)
+  #       # You can give attribute a block and it will be called on the object
+  #       # instance. This lets you rename or compute attributes
+  #       attribute(:full_name) { "#{first_name} #{last_name}" }
+  #
+  #       # Relationship requires a minimum of 2 parameters. The first is the name
+  #       # of the relationship in the rendered JSON. The second is the type.
+  #       # When fetching the value, Onsi will add `_id` and call that method on the
+  #       # object instance. e.g. `team_id` in this case.
+  #       relationship(:team, :team)
+  #
+  #       # Relationships can take a block that will be called on the object instance
+  #       # and the return value will be used as the ID
+  #       relationship(:primary_email, :email) { emails.where(primary: true).first.id }
+  #     end
+  #   end
   module Model
-    DEFAULT_API_VERSION = :v1
-
     extend ActiveSupport::Concern
 
+    ##
+    # The current default rendered API version.
+    DEFAULT_API_VERSION = :v1
+
+    ##
+    # Defines class methods available on the class.
     module ClassMethods
+      ##
+      # Add a version to be rendered.
+      #
+      # @param version [Symbol] The version that will trigger this render block.
+      #
+      # @param block [Block] The block. Called on an instance
+      #   of {Onsi::Model::ModelRenderer}
       def api_render(version, &block)
         api_renderer(version).instance_exec(&block)
       end
 
+      ##
+      # Fetch the {Onsi::Model::ModelRenderer} for the version.
+      #
+      # @param version [Symbol] The version to fetch the renderer for.
+      #
+      # @param for_render [true, false] Specifies if the version should be
+      #   required to exist. Should only ever be true when attempting to render
+      #   the resource.
+      #
+      # @raise [Onsi::Errors::UnknownVersionError] If the version isn't defined
+      #   and the for_render param is true.
       def api_renderer(version, for_render: false)
         @api_renderer ||= {}
         if for_render
@@ -20,95 +72,174 @@ module Onsi
         end
         @api_renderer[version]
       end
+    end
 
-      class ModelRenderer
-        DATE_FORMAT = '%Y-%m-%d'.freeze
-        DATETIME_FORMAT = '%Y-%m-%dT%H:%M:%SZ'.freeze
-
-        def initialize
-          @attributes = {}
-          @relationships = {}
-          @metadata = {}
-        end
+    ##
+    # The class that holds attributes and relationships for a model's version.
+    #
+    # @note You shouldn't ever have to directly interact with one of
+    #   these classes.
+    #
+    # @author Maddie Schipper
+    # @since 1.0.0
+    class ModelRenderer
+      ##
+      # The default date format for a rendered Date. (ISO-8601)
+      DATE_FORMAT = '%Y-%m-%d'.freeze
+
+      ##
+      # The default date-time format for a rendered Date and Time. (ISO-8601)
+      DATETIME_FORMAT = '%Y-%m-%dT%H:%M:%SZ'.freeze
+
+      ##
+      # Create a new ModelRenderer
+      #
+      # @private
+      def initialize
+        @attributes = {}
+        @relationships = {}
+        @metadata = {}
+      end
 
-        def type(name = nil)
-          @type = name if name
-          @type
-        end
+      ##
+      # The type name.
+      #
+      # @param name [String, nil] The resource object type name.
+      #
+      # @note Not required. If there is no type, the class name will be used
+      #   when rendering the object. (Name is underscored)
+      def type(name = nil)
+        @type = name if name
+        @type
+      end
 
-        def attribute(name, &block)
-          @attributes[name.to_sym] = block || name
-        end
+      ##
+      # Add an attribute to the rendered attributes.
+      #
+      # @param name [String, Symbol, #to_sym] The name of the attribute.
+      #   If no block is passed the name will be called on
+      #   the {Onsi::Resource#object}
+      #
+      # @param block [Block] The block used to fetch a dynamic attribute.
+      #   It will be executed in the context of the {Onsi::Resource#object}
+      #
+      # @example
+      #   api_render(:v1) do
+      #     attribute(:first_name)
+      #     attribute(:last_name)
+      #     attribute(:full_name) { "#{first_name} #{last_name}" }
+      #
+      #     # ...
+      #
+      #   end
+      def attribute(name, &block)
+        @attributes[name.to_sym] = block || name
+      end
 
-        def relationship(name, type, &block)
-          @relationships[name.to_sym] = { type: type, attr: block || name }
-        end
+      ##
+      # Add a relationship to the rendered relationships.
+      #
+      # @param name [Symbol, #to_sym] The relationship name.
+      #
+      # @param type [String, #to_s] The relationship type.
+      #
+      # @param block [Block] The block used to fetch a dynamic attribute.
+      #   It will be executed in the context of the {Onsi::Resource#object}
+      #
+      # @example
+      #   api_render(:v1) do
+      #     relationship(:team, :team)
+      #
+      #     # ...
+      #
+      #   end
+      def relationship(name, type, &block)
+        @relationships[name.to_sym] = { type: type, attr: block || name }
+      end
 
-        def meta(name, &block)
-          @metadata[name.to_sym] = block
-        end
+      ##
+      # Add a metadata value to the rendered object's meta.
+      #
+      # @param name [#to_sym] The name for the meta value.
+      #
+      # @param block [Block] The block used to fetch the meta value.
+      #   It will be executed in the context of the {Onsi::Resource#object}
+      def meta(name, &block)
+        @metadata[name.to_sym] = block
+      end
 
-        def render_attributes(object)
-          @attributes.each_with_object({}) do |(key, value), attrs|
-            val = value.respond_to?(:call) ? object.instance_exec(&value) : object.send(value)
-            attrs[key.to_s] = format_attribute(val)
-          end
+      ##
+      # Render all attributes
+      #
+      # @private
+      def render_attributes(object)
+        @attributes.each_with_object({}) do |(key, value), attrs|
+          val = value.respond_to?(:call) ? object.instance_exec(&value) : object.send(value)
+          attrs[key.to_s] = format_attribute(val)
         end
+      end
 
-        def render_relationships(object)
-          @relationships.each_with_object({}) do |(key, value), rels|
-            render_relationship_entry(object, key, value, rels)
-          end
+      ##
+      # Render all relationships
+      #
+      # @private
+      def render_relationships(object)
+        @relationships.each_with_object({}) do |(key, value), rels|
+          render_relationship_entry(object, key, value, rels)
         end
+      end
 
-        def render_metadata(object)
-          @metadata.each_with_object({}) do |(key, block), meta|
-            meta[key.to_s] = object.instance_exec(&block)
-          end
+      ##
+      # Render all metadata
+      #
+      # @private
+      def render_metadata(object)
+        @metadata.each_with_object({}) do |(key, block), meta|
+          meta[key.to_s] = object.instance_exec(&block)
         end
+      end
 
-        private
+      private
 
-        def render_relationship_entry(object, key, value, rels)
-          attr = value[:attr]
-          relationship = get_relationship_value(attr, object)
-          data = format_relationship(relationship, value)
-          rels[key.to_s] = {
-            'data' => data
-          }
-        end
+      def render_relationship_entry(object, key, value, rels)
+        attr = value[:attr]
+        relationship = get_relationship_value(attr, object)
+        data = format_relationship(relationship, value)
+        rels[key.to_s] = {
+          'data' => data
+        }
+      end
 
-        def get_relationship_value(attr, object)
-          if attr.respond_to?(:call)
-            object.instance_exec(&attr)
-          else
-            object.send("#{attr}_id")
-          end
+      def get_relationship_value(attr, object)
+        if attr.respond_to?(:call)
+          object.instance_exec(&attr)
+        else
+          object.send("#{attr}_id")
         end
+      end
 
-        def format_relationship(relationship, value)
-          case relationship
-          when Array
-            relationship.map { |v| { 'type' => value[:type].to_s, 'id' => v.to_s } }
-          else
-            {
-              'type' => value[:type].to_s,
-              'id' => relationship.to_s
-            }
-          end
+      def format_relationship(relationship, value)
+        case relationship
+        when Array
+          relationship.map { |v| { 'type' => value[:type].to_s, 'id' => v.to_s } }
+        else
+          {
+            'type' => value[:type].to_s,
+            'id' => relationship.to_s
+          }
         end
+      end
 
-        def format_attribute(value)
-          case value
-          when Date
-            value.strftime(DATE_FORMAT)
-          when DateTime, Time
-            value.utc.strftime(DATETIME_FORMAT)
-          when String
-            value.presence
-          else
-            value
-          end
+      def format_attribute(value)
+        case value
+        when Date
+          value.strftime(DATE_FORMAT)
+        when DateTime, Time
+          value.utc.strftime(DATETIME_FORMAT)
+        when String
+          value.presence
+        else
+          value
         end
       end
     end

data/lib/onsi/params.rb

@@ -1,36 +1,75 @@
+require_relative 'errors'
+
 module Onsi
   ##
   # Used to handle parsing JSON-API formated params
+  #
+  # @example
+  #   class PeopleController < ApplicationController
+  #     include Onsi::Controller
+  #
+  #     def create
+  #       attributes = Onsi::Param.parse(
+  #         params,
+  #         [:first_name, :last_name],
+  #         [:team]
+  #       )
+  #       render_resource Person.create!(attributes.flatten)
+  #     end
+  #   end
   class Params
     ##
-    # Raised when using `Params#safe_fetch`
+    # Raised when a safe_fetch fails.
     #
-    # The ErrorResponder will rescue from this and return an appropriate
-    # error to the user
-    class RelationshipNotFound < StandardError
+    # @note The ErrorResponder will rescue from this and return an appropriate
+    #   error to the user
+    class RelationshipNotFound < Onsi::Errors::BaseError
+      ##
+      # The key that the relationship wasn't found for
+      #
+      # @return [String]
       attr_reader :key
 
+      ##
+      # @private
       def initialize(message, key)
         super(message)
-        @key = key
+        @key = key.to_s
       end
     end
 
     ##
     # Raised when a required attribute has a nil value. `Params#require`
     #
-    # The ErrorResponder will rescue from this and return an appropriate
-    # error to the user
-    class MissingReqiredAttribute < StandardError
+    # @note The ErrorResponder will rescue from this and return an appropriate
+    #   error to the user
+    class MissingReqiredAttribute < Onsi::Errors::BaseError
+      ##
+      # The attribute that was missing when required.
+      #
+      # @return [String]
       attr_reader :attribute
 
+      ##
+      # @private
       def initialize(message, attr)
         super(message)
-        @attribute = attr
+        @attribute = attr.to_s
       end
     end
 
     class << self
+      ##
+      # Parse a JSON-API formatted params object.
+      #
+      # @param params [ActionController::Parameters] The parameters to parse.
+      #
+      # @param attributes [Array<String, Symbol>] The whitelisted attributes.
+      #
+      # @param relationships [Array<String, Symbol>] The whitelisted relationships.
+      #   Should be the key for the relationships name.
+      #
+      # @return [Params] The new params object.
       def parse(params, attributes = [], relationships = [])
         data = params.require(:data)
         data.require(:type)
@@ -39,6 +78,17 @@ module Onsi
         new(attrs, relas)
       end
 
+      ##
+      # Parse a JSON-API formatted JSON object.
+      #
+      # @param body [String, #read] The parameters to parse.
+      #
+      # @param attributes [Array<String, Symbol>] The whitelisted attributes.
+      #
+      # @param relationships [Array<String, Symbol>] The whitelisted relationships.
+      #   Should be the key for the relationships name.
+      #
+      # @return [Onsi::Params] The new params object.
       def parse_json(body, attributes = [], relationships = [])
         content = body.respond_to?(:read) ? body.read : body
         json = JSON.parse(content)
@@ -104,8 +154,28 @@ module Onsi
       end
     end
 
-    attr_reader :attributes, :relationships
+    ##
+    # The attributes for the params.
+    #
+    # @return [ActionController::Parameters]
+    attr_reader :attributes
+
+    ##
+    # The relationships for the params.
+    #
+    # @return [Hash]
+    attr_reader :relationships
 
+    ##
+    # Create a new Params instance.
+    #
+    # @param attributes [ActionController::Parameters] The attributes
+    #
+    # @param relationships [Hash] Flattened relationships hash
+    #
+    # @note Should not be created directly. Use .parse or .parse_json
+    #
+    # @private
     def initialize(attributes, relationships)
       @attributes = attributes
       @relationships = relationships
@@ -113,12 +183,20 @@ module Onsi
 
     ##
     # Flatten an merge the attributes & relationships into one hash.
+    #
+    # @return [Hash] The flattened attributes and relationships
     def flatten
       attrs_hash.to_h.merge(relationships.to_h).with_indifferent_access
     end
 
     ##
     # Fetch a value from the attributes or return the passed default value
+    #
+    # @param key [String, Symbol] The key to fetch.
+    #
+    # @param default [Any] The default value if the attribute doesn't exist.
+    #
+    # @return [Any]
     def fetch(key, default = nil)
       attrs_hash[key] || default
     end
@@ -126,7 +204,11 @@ module Onsi
     ##
     # Make an attributes key required.
     #
-    # Throws MissingReqiredAttribute if the value is nil
+    # @param key [String, Symbol] The key of the attribute to require.
+    #
+    # @raise [MissingReqiredAttribute] The value you have required isn't present
+    #
+    # @return [Any] The value for the attribute
     def require(key)
       value = attrs_hash[key]
       if value.nil?
@@ -137,14 +219,19 @@ module Onsi
     end
 
     ##
-    # Handle finding a relationship's object
+    # Handle finding a relationship's object.
+    #
+    # @param key [String, Symbol] The key for the relationship
     #
-    # If an ActiveRecord::RecordNotFound is raised, a RelationshipNotFound error will
-    # be raised so the ErrorResponder can build an appropriate error message
+    # @raise [RelationshipNotFound] Thrown instead of an `ActiveRecord::RecordNotFound`
+    #   This allows the `Onsi::ErrorResponder` to build an appropriate response.
     #
-    # params.safe_fetch(:person) do |id|
-    #   Person.find(id)
-    # end
+    # @example
+    #   params.safe_fetch(:person) do |id|
+    #     Person.find(id)
+    #   end
+    #
+    # @return [Any]
     def safe_fetch(key)
       yield(@relationships[key])
     rescue ActiveRecord::RecordNotFound
@@ -156,21 +243,36 @@ module Onsi
     #
     # Any getter will run the value through the transform block.
     #
-    # (The values are memoized)
+    # @param key [String, Symbol] The key to transform.
+    #
+    # @param block [Block] The block to perform the transform.
+    #
+    # @note The values are memoized
     #
-    # `params.transform(:date) { |date| Time.parse(date) }`
+    # @example
+    #   params.transform(:date) { |date| Time.parse(date) }
+    #
+    # @return [Any]
     def transform(key, &block)
       @attrs_hash = nil
       transforms[key.to_sym] = block
     end
 
     ##
-    # Set a default value.
+    # Set a default value for attributes.
     #
     # This value will only be used if the key is missing from the passed attributes
     #
-    # Can take any object. If the object responds to call (Lambda) it will be called when
-    # parsing attributes
+    # @param key [String, Symbol] The key to set a default on.
+    #
+    # @param value [Any, #call] The default value.
+    #   If the object responds to call (Lambda) it will be called when
+    #   parsing attributes
+    #
+    # @example
+    #   params.default(:missing, -> { :foo })
+    #   subject.flatten[:missing]
+    #   # => :foo
     def default(key, value)
       @attrs_hash = nil
       defaults[key.to_sym] = value

data/lib/onsi/resource.rb

@@ -1,18 +1,72 @@
+require_relative 'errors'
+
 module Onsi
+  ##
+  # The wrapper for generating a object
+  #
+  # @author Maddie Schipper
+  # @since 1.0.0
   class Resource
-    attr_reader :object, :version, :includes
+    ##
+    # Root object type key
+    #
+    # @private
+    TYPE_KEY = 'type'.freeze
+
+    ##
+    # Root object id key
+    #
+    # @private
+    ID_KEY = 'id'.freeze
+
+    ##
+    # Root object attributes key
+    #
+    # @private
+    ATTRIBUTES_KEY = 'attributes'.freeze
 
-    TYPE_KEY          = 'type'.freeze
-    ID_KEY            = 'id'.freeze
-    ATTRIBUTES_KEY    = 'attributes'.freeze
+    ##
+    # Root object relationships key
+    #
+    # @private
     RELATIONSHIPS_KEY = 'relationships'.freeze
-    META_KEY          = 'meta'.freeze
-    DATA_KEY          = 'data'.freeze
-    INCLUDED_KEY      = 'included'.freeze
 
-    class InvalidResourceError < StandardError; end
+    ##
+    # Root object meta key
+    #
+    # @private
+    META_KEY = 'meta'.freeze
+
+    ##
+    # Root object data key
+    #
+    # @private
+    DATA_KEY = 'data'.freeze
+
+    ##
+    # Root object included key
+    #
+    # @private
+    INCLUDED_KEY = 'included'.freeze
+
+    ##
+    # Raised if the resource or includes are invalid.
+    class InvalidResourceError < Onsi::Errors::BaseError; end
 
     class << self
+      ##
+      # Convert an object into a Onsi::Resource
+      #
+      # @param resource [Onsi::Resource, Enumerable, ActiveRecord::Base] The
+      #   object to be converted.
+      #   - If a Onsi::Resource is passed it will be directly returned.
+      #   - If an Enumerable is passed #map will be called and .as_resource will
+      #     be recursivly called for each object.
+      #   - If any other object is passed it will be wrapped in a Onsi::Resource
+      #
+      # @param version [Symbol] The version of the resource. `:v1`
+      #
+      # @return [Onsi::Resource, Array<Onsi::Resource>]
       def as_resource(resource, version)
         case resource
         when Onsi::Resource
@@ -24,6 +78,15 @@ module Onsi
         end
       end
 
+      ##
+      # Render a resource to JSON
+      #
+      # @param resource (see .as_resource)
+      #
+      # @param version [Symbol] The version to render as. `:v1`
+      #
+      # @return [Hash] The rendered resource as a hash ready to be converted
+      #   to JSON.
       def render(resource, version)
         resources = as_resource(resource, version)
         {}.tap do |root|
@@ -35,6 +98,8 @@ module Onsi
         end
       end
 
+      private
+
       def all_included(resources)
         Array(resources).map(&:flat_includes).flatten.uniq do |res|
           "#{res[TYPE_KEY]}-#{res[ID_KEY]}"
@@ -42,6 +107,39 @@ module Onsi
       end
     end
 
+    ##
+    # The backing object.
+    #
+    # @note MUST include Onsi::Model
+    #
+    # @return [Any] The object to be rendered by the resource.
+    attr_reader :object
+
+    ##
+    # The version to render.
+    #
+    # @return [Symbol]
+    attr_reader :version
+
+    ##
+    # The includes for the object.
+    #
+    # @return [Array<Onsi::Includes>]
+    attr_reader :includes
+
+    ##
+    # Create a new resouce.
+    #
+    # @param object [Any] The resource backing object.
+    #
+    # @param version [Symbol] The version to render. Can be nil. If nil is
+    #   passed the DEFAULT_API_VERSION will be used.
+    #
+    # @note The object MUST be a single object that includes Onsi::Model
+    #
+    # @note The includes MUST be an array of Onsi::Include objects.
+    #
+    # @return [Onsi::Resource] The new resource
     def initialize(object, version = nil, includes: nil)
       @object  = object
       @version = version || Model::DEFAULT_API_VERSION
@@ -49,6 +147,10 @@ module Onsi
       validate!
     end
 
+    ##
+    # Creates a raw JSON object.
+    #
+    # @return [Hash]
     def as_json(_opts = {})
       {}.tap do |root|
         root[TYPE_KEY] = type
@@ -60,10 +162,18 @@ module Onsi
       end
     end
 
+    ##
+    # All rendered includes
+    #
+    # @private
     def rendered_includes
       @rendered_includes ||= perform_render_includes
     end
 
+    ##
+    # Flat includes
+    #
+    # @private
     def flat_includes
       rendered_includes.values.map { |root| root[DATA_KEY] }.flatten
     end

data/lib/onsi/version.rb

@@ -1,3 +1,5 @@
 module Onsi
-  VERSION = '0.8.0'.freeze
+  ##
+  # The current version of Onsi
+  VERSION = '1.0.0'.freeze
 end

data/onsi.gemspec

@@ -32,4 +32,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rspec-rails',      '~> 3.7.2'
   spec.add_development_dependency 'simplecov',        '~> 0.15'
   spec.add_development_dependency 'sqlite3',          '~> 1.3.10'
+  spec.add_development_dependency 'yard',             '~> 0.9.16'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: onsi
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Maddie Schipper
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-11-13 00:00:00.000000000 Z
+date: 2018-11-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -142,6 +142,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.3.10
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.16
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.16
 description: Format JSON API responses and parse inbound requests.
 email:
 - me@maddiesch.com
@@ -154,6 +168,8 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
+- ".yardopts"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md