resting_pug 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f7d99d102f6977a7fce1ac74ae7b1489d95273d7
-  data.tar.gz: ba714667deb6cfc2bc48a39085bf1f18a2954845
+  metadata.gz: 927bf0f8f98d894ab8421feb896b4a64b44f35eb
+  data.tar.gz: aae8c437373e4c033ba0dc2490a71a6e9e1064f1
 SHA512:
-  metadata.gz: 062416d0fe7ee490e6ddd9cfb7b7b3fe8cd94d738a5579e0d8801794dd940012a9c3ccf456b223e42a2d41cc4c5f82d0d61857c7d62663378748fff484e9f487
-  data.tar.gz: ebb18d667055f77993629cb8320920e410fed4b221dde060ab0709a267ceb11d46701ad1e168bf70708ac88e2c478a69e06b127ef6dab818d71520dc9007356b
+  metadata.gz: 9fbce2102a15bb5ca3c3cbb74417cfb7fb2edeb16f1bc333067cb0e48a8a83be69fc7269e380d9207a357ea1b57f33f0bdba45ed1f0a7a3f4d8d5a48fc3249c7
+  data.tar.gz: 9fd83245c3efaad741b2b61cd6f43130a2c407d5e9a1746327ada9fc6b273f23a013c7e9ed196203cc0c42ab12a37c2d649e9119bf54756a93ace75cea2a8c32

data/README.md

@@ -1,15 +1,79 @@
 
 <h1 align="center">
   <br>
-  <a href="https://korolvs.github.com/resting_pug"><img src="https://korolvs.github.com/resting_pug/resting_pug.png" alt="Markdownify" width="80%"></a>
+  <a href="https://korolvs.github.com/resting_pug"><img src="https://korolvs.github.com/resting_pug/logo.svg" alt="Logo" width="80%"></a>
   <br>
 </h1>
 
-# Basic Overview
+[![Gem Version](https://badge.fury.io/rb/resting_pug.svg)](https://badge.fury.io/rb/resting_pug)
+[![Maintainability](https://api.codeclimate.com/v1/badges/e53c62ffa3ee4cba3895/maintainability)](https://codeclimate.com/github/korolvs/resting_pug/maintainability)
+[![Build Status](https://travis-ci.org/korolvs/resting_pug.svg?branch=master)](https://travis-ci.org/korolvs/resting_pug)
+[![codecov](https://codecov.io/gh/korolvs/resting_pug/branch/master/graph/badge.svg)](https://codecov.io/gh/korolvs/resting_pug)
+
+## Table of Contents
+
+- [What is Resting Pug?](#what-is-resting-pug)
+- [Why should I use it?](#why-should-i-use-it)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Created actions and thing that you can customize](#created-actions-and-things-you-can-customize)
+  - [Create](#create)
+  - [Update](#update)
+  - [Destroy](#destroy)
+  - [Show](#show)
+  - [Index](#index)
+- [Contributing](#contributing)
+- [Changelog](#changelog)
+- [License](#license)
+
+## What is Resting Pug?
 Resting Pug allows you to create a JSON API with just adding one line to your controller and fully customize it with overriding small and simple helper methods.
 
+## Why should I use it?
+Often when you want to try a new idea or create a simple app you want to implement basic features very fast.
+Resting Pug allows you to do it with just couple lines of code.
+But even though it is small and simple(and because it is small and simple) you can vastly customize created API.
+Attributes user can see, attributes user can edit, number of items on page, how to render items and errors - thats just a small part of things you can change overriding basic Resting Pug methods.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'resting_pug'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
 ## Usage
-Include ```RestingPug::Base``` into controller to add CRUD actions to it:
+
+**1. Create a model that will be accesible through API:**
+
+```ruby
+class Book < ApplicationRecord
+  validates :title, presence: true, length: { minimum: 3 }
+  validates :author, presence: true, length: { minimum: 3 }
+end
+```
+
+```ruby
+class CreateBooks < ActiveRecord::Migration
+  def change
+    create_table :books do |t|
+      t.string :title
+      t.string :author
+      t.integer :year
+      t.integer :rating
+
+      t.timestamps
+    end
+  end
+end
+```
+
+**2. Create a new controller and include ```RestingPug::Base``` into it to add CRUD actions:**
 
 ```ruby
 class BooksController < ApplicationController
@@ -25,7 +89,7 @@ class ApplicationController < ActionController::Base
 end
 ```
 
-Don't forget to add a route to ```config/routes.rb``` 
+**3. Don't forget to add a route to ```config/routes.rb```**
 
 ```ruby
 Rails.application.routes.draw do
@@ -33,20 +97,162 @@ Rails.application.routes.draw do
 end
 ```
 
-## Installation
-Add this line to your application's Gemfile:
+**4. Enjoy your new API and don't hesitate to change it whatever you want!**
+
+## List of actions and things that you can customize
+Actions created after including ```RestingPug::Base```:
+
+### Create
 
-```ruby
-gem 'resting_pug'
 ```
+Request:
+POST http://your.awesome/api/books
+{
+  "name": "11/22/63",
+  "author": "Stephen King"
+}
+
+Response:
+200 OK
+{
+  "book": {
+    "id": 1,
+    "name": "11/22/63",
+    "author": "Stephen King"
+  }
+}
+```
+
+Things you can customize:
+
+- override [permitted_fields_for_create](https://korolvs.github.com/resting_pug/0.1.1/params/permitted_fields_for_create) to set which params can be set in a new subject
+- override [permitted_fields_for_show](https://korolvs.github.com/resting_pug/0.1.1/params/permitted_fields_for_show) to set which params will be shown in response
+- override [render_subject](https://korolvs.github.com/resting_pug/0.1.1/render/render_subject) to set how subject will be rendered
+- override [render_errors](https://korolvs.github.com/resting_pug/0.1.1/render/render_errors) to set how errors will be rendered
+- override [subject_model](https://korolvs.github.com/resting_pug/0.1.1/subject/subject_model) to set what model will be created
+- override [create_chain](https://korolvs.github.com/resting_pug/0.1.1/chains/create_chain) to add or remove methods which will be called while creating a subject
+- override [decide_what_to_render](https://korolvs.github.com/resting_pug/0.1.1/render/decide_what_to_render) to set how it will be decided what to render in response
+
+### Update
+
+```
+Request:
+PATCH http://your.awesome/api/books/1
+{
+  "name": "The Green Mile",
+}
+
+Response:
+200 OK
+{
+  "book": {
+    "id": 1,
+    "name": "The Green Mile",
+    "author": "Stephen King"
+  }
+}
+```
+
+Things you can customize:
+
+- override [permitted_fields_for_update](https://korolvs.github.com/resting_pug/0.1.1/params/permitted_fields_for_update) to set which params can be updated
+- override [permitted_fields_for_show](https://korolvs.github.com/resting_pug/0.1.1/params/permitted_fields_for_show) to set which params will be shown in response
+- override [render_subject](https://korolvs.github.com/resting_pug/0.1.1/render/render_subject) to set how subject will be rendered
+- override [render_errors](https://korolvs.github.com/resting_pug/0.1.1/render/render_errors) to set how errors will be rendered
+- override [render_not_found](https://korolvs.github.com/resting_pug/0.1.1/render/render_not_found) to set what to render when subject with ID from params is not found
+- override [subject_model](https://korolvs.github.com/resting_pug/0.1.1/subject/subject_model) to set what model will be updated
+- override [update_chain](https://korolvs.github.com/resting_pug/0.1.1/chains/update_chain) to add or remove methods which will be called while updating a subject
+- override [decide_what_to_render](https://korolvs.github.com/resting_pug/0.1.1/render/decide_what_to_render) to set how it will be decided what to render in response
+
+### Destroy
+
+```
+Request:
+DELETE http://your.awesome/api/books/1
+
+Response:
+204 No Content
+```
+
+Things you can customize:
+
+- override [destroy_subject](https://korolvs.github.com/resting_pug/0.1.1/subject/destroy_subject) to set how it will be destroyed
+- override [render_nothing](https://korolvs.github.com/resting_pug/0.1.1/render/render_nothing) to set what to render when subject is destroyed
+- override [render_errors](https://korolvs.github.com/resting_pug/0.1.1/render/render_errors) to set how errors will be rendered
+- override [render_not_found](https://korolvs.github.com/resting_pug/0.1.1/render/render_not_found) to set what to render when subject with ID from params is not found
+- override [subject_model](https://korolvs.github.com/resting_pug/0.1.1/subject/subject_model) to set what model will be deleted
+- override [destroy_chain](https://korolvs.github.com/resting_pug/0.1.1/chains/destroy_chain) to add or remove methods which will be called while deleting a subject
+
+### Show
 
-And then execute:
-```bash
-$ bundle
 ```
+Request:
+GET http://your.awesome/api/books/1
+
+Response:
+200 OK
+{
+  "book": {
+    "id": 1,
+    "name": "The Green Mile",
+    "author": "Stephen King"
+  }
+}
+```
+
+Things you can customize:
+
+- override [permitted_fields_for_show](https://korolvs.github.com/resting_pug/0.1.1/params/permitted_fields_for_show) to set which params will be shown in response
+- override [render_subject](https://korolvs.github.com/resting_pug/0.1.1/render/render_subject) to set how subject will be rendered
+- override [render_not_found](https://korolvs.github.com/resting_pug/0.1.1/render/render_not_found) to set what to render when subject with ID from params is not found
+- override [subject_model](https://korolvs.github.com/resting_pug/0.1.1/subject/subject_model) to set what model will be shown
+- override [show_chain](https://korolvs.github.com/resting_pug/0.1.1/chains/show_chain) to add or remove methods which will be called while updating a subject
+
+### Index
+
+```
+Request:
+GET http://your.awesome/api/books
+GET http://your.awesome/api/books?filter[author]="King"
+GET http://your.awesome/api/books?filter[author][]="King"&filter[author][]="Kesey"
+GET http://your.awesome/api/books?sort=-id,name,-author
+GET http://your.awesome/api/books?page=3&per_page=10
+GET http://your.awesome/api/books?filter[author]="King"&sort=-id?page=3&per_page=10
+
+Response:
+200 OK
+{
+  "books": [{
+    "id": 2,
+    "name": "The Green Mile",
+    "author": "Stephen King"
+  }, {
+    "id": 1,
+    "name": "11/22/63",
+    "author": "Stephen King"
+  }]
+}
+```
+
+Things you can customize:
+
+- override [permitted_fields_for_show](https://korolvs.github.com/resting_pug/0.1.1/params/permitted_fields_for_show) to set which params will be shown in response
+- override [permitted_fields_for_filter](https://korolvs.github.com/resting_pug/0.1.1/params/permitted_fields_for_filter) to set which params can be used for filtering
+- override [permitted_fields_for_sort](https://korolvs.github.com/resting_pug/0.1.1/params/permitted_fields_for_sort) to set which params can be used for sorting
+- override [default_sort_params](https://korolvs.github.com/resting_pug/0.1.1/params/default_sort_params) to set default sort params
+- override [per_page_default](https://korolvs.github.com/resting_pug/0.1.1/params/per_page_default) to set default per_page param
+- override [per_page_range](https://korolvs.github.com/resting_pug/0.1.1/params/per_page_range) to set minimum and maximum possible per_page value
+- override [render_subjects](https://korolvs.github.com/resting_pug/0.1.1/render/render_subjects) to set how subjects will be rendered
+- override [subject_model](https://korolvs.github.com/resting_pug/0.1.1/subject/subject_model) to set what model will be shown
+- override [index_chain](https://korolvs.github.com/resting_pug/0.1.1/chains/index_chain) to add or remove methods which will be called while updating a subject
 
 ## Contributing
-Contribution directions go here.
+You're encouraged to submit [pull requests](https://github.com/korolvs/resting_pug/pulls), [propose features and discuss issues](https://github.com/korolvs/resting_pug/issues).
+
+See [CONTRIBUTING](CONTRIBUTING.md)
+
+## Changelog
+To see what has changed in recent versions of Resting Pug, see the [CHANGELOG](CHANGELOG.md).
 
 ## License
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -20,4 +20,6 @@ end
 
 
 require 'bundler/gem_tasks'
-
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new('spec')
+task default: :spec

data/lib/resting_pug/actions.rb

@@ -1,5 +1,6 @@
 module RestingPug
-  # Describes basic CRUD actions
+  # Describes basic CRUD actions.
+  # Each action is represented by a chain of methods definied in {Chains} module.
   # @see https://en.wikipedia.org/wiki/Create,_read,_update_and_delete
   # @used_in {Base.included}
   module Actions
@@ -22,13 +23,13 @@ module RestingPug
     #     }
     #   }
     # @note You can sustomize creating action:
-    #   - override {Subject#subject_model} to set what model will be created
-    #   - override {Chains#create_chain} to add or remove methods which will be called while creating a subject
-    #   - override {Params#permitted_fields_for_create} to set which params can be set in a new subject
-    #   - override {Params#permitted_fields_for_show} to set which params will be shown in response
-    #   - override {Render#decide_what_to_render} to set how it will be decided what to render in response
-    #   - override {Render#render_subject} to set how subject will be rendered
-    #   - override {Render#render_errors} to set how errors will be rendered
+    #   - override {Params#permitted_fields_for_create permitted_fields_for_create} to set which params can be set in a new subject
+    #   - override {Params#permitted_fields_for_show permitted_fields_for_show} to set which params will be shown in response
+    #   - override {Render#render_subject render_subject} to set how subject will be rendered
+    #   - override {Render#render_errors render_errors} to set how errors will be rendered
+    #   - override {Subject#subject_model subject_model} to set what model will be created
+    #   - override {Chains#create_chain create_chain} to add or remove methods which will be called while creating a subject
+    #   - override {Render#decide_what_to_render decide_what_to_render} to set how it will be decided what to render in response
     # @use {#run_chain}
     # @use {Chains#create_chain}
     def create
@@ -53,14 +54,14 @@ module RestingPug
     #     }
     #   }
     # @note You can sustomize creating action:
-    #   - override {Subject#subject_model} to set what model will be updated
-    #   - override {Chains#update_chain} to add or remove methods which will be called while updating a subject
-    #   - override {Params#permitted_fields_for_update} to set which params can be updated
-    #   - override {Params#permitted_fields_for_show} to set which params will be shown in response
-    #   - override {Render#decide_what_to_render} to set how it will be decided what to render in response
-    #   - override {Render#render_subject} to set how subject will be rendered
-    #   - override {Render#render_errors} to set how errors will be rendered
-    #   - override {Render#render_not_found} to set what to render when subject with ID from params is not found
+    #   - override {Params#permitted_fields_for_update permitted_fields_for_update} to set which params can be updated
+    #   - override {Params#permitted_fields_for_show permitted_fields_for_show} to set which params will be shown in response
+    #   - override {Render#render_subject render_subject} to set how subject will be rendered
+    #   - override {Render#render_errors render_errors} to set how errors will be rendered
+    #   - override {Render#render_not_found render_not_found} to set what to render when subject with ID from params is not found
+    #   - override {Subject#subject_model subject_model} to set what model will be updated
+    #   - override {Chains#update_chain update_chain} to add or remove methods which will be called while updating a subject
+    #   - override {Render#decide_what_to_render decide_what_to_render} to set how it will be decided what to render in response
     # @use {#run_chain}
     # @use {Chains#update_chain}
     def update
@@ -75,12 +76,12 @@ module RestingPug
     #   Response:
     #   204 No Content
     # @note You can sustomize creating action:
-    #   - override {Subject#subject_model} to set what model will be deleted
-    #   - override {Chains#destroy_chain} to add or remove methods which will be called while deleting a subject
-    #   - override {Subject#destroy_subject} to set how it will be destroyed
-    #   - override {Render#render_nothing} to set what to render when subject is destroyed
-    #   - override {Render#render_errors} to set how errors will be rendered
-    #   - override {Render#render_not_found} to set what to render when subject with ID from params is not found
+    #   - override {Subject#destroy_subject destroy_subject} to set how it will be destroyed
+    #   - override {Render#render_nothing render_nothing} to set what to render when subject is destroyed
+    #   - override {Render#render_errors render_errors} to set how errors will be rendered
+    #   - override {Render#render_not_found render_not_found} to set what to render when subject with ID from params is not found
+    #   - override {Subject#subject_model subject_model} to set what model will be deleted
+    #   - override {Chains#destroy_chain destroy_chain} to add or remove methods which will be called while deleting a subject
     # @use {#run_chain}
     # @use {Chains#destroy_chain}
     def destroy
@@ -102,11 +103,11 @@ module RestingPug
     #     }
     #   }
     # @note You can sustomize creating action:
-    #   - override {Subject#subject_model} to set what model will be shown
-    #   - override {Chains#show_chain} to add or remove methods which will be called while updating a subject
-    #   - override {Params#permitted_fields_for_show} to set which params will be shown in response
-    #   - override {Render#render_subject} to set how subject will be rendered
-    #   - override {Render#render_not_found} to set what to render when subject with ID from params is not found
+    #   - override {Params#permitted_fields_for_show permitted_fields_for_show} to set which params will be shown in response
+    #   - override {Render#render_subject render_subject} to set how subject will be rendered
+    #   - override {Render#render_not_found render_not_found} to set what to render when subject with ID from params is not found
+    #   - override {Subject#subject_model subject_model} to set what model will be shown
+    #   - override {Chains#show_chain show_chain} to add or remove methods which will be called while updating a subject
     # @use {#run_chain}
     # @use {Chains#show_chain}
     def show
@@ -140,15 +141,15 @@ module RestingPug
     #     }]
     #   }
     # @note You can sustomize creating action:
-    #   - override {Subject#subject_model} to set what model will be shown
-    #   - override {Chains#index_chain} to add or remove methods which will be called while updating a subject
-    #   - override {Params#permitted_fields_for_show} to set which params will be shown in response
-    #   - override {Params#permitted_fields_for_filter} to set which params can be used for filtering
-    #   - override {Params#permitted_fields_for_sort} to set which params can be used for sorting
-    #   - override {Params#default_sort_params} to set default sort params
-    #   - override {Params#per_page_default} to set default per_page param
-    #   - override {Params#per_page_range} to set minimum and maximum possible per_page value
-    #   - override {Render#render_subjects} to set how subjects will be rendered
+    #   - override {Params#permitted_fields_for_show permitted_fields_for_show} to set which params will be shown in response
+    #   - override {Params#permitted_fields_for_filter permitted_fields_for_filter} to set which params can be used for filtering
+    #   - override {Params#permitted_fields_for_sort permitted_fields_for_sort} to set which params can be used for sorting
+    #   - override {Params#default_sort_params default_sort_params} to set default sort params
+    #   - override {Params#per_page_default per_page_default} to set default per_page param
+    #   - override {Params#per_page_range per_page_range} to set minimum and maximum possible per_page value
+    #   - override {Render#render_subjects render_subjects} to set how subjects will be rendered
+    #   - override {Subject#subject_model subject_model} to set what model will be shown
+    #   - override {Chains#index_chain index_chain} to add or remove methods which will be called while updating a subject
     # @use {#run_chain}
     # @use {Chains#index_chain}
     def index
@@ -159,6 +160,11 @@ module RestingPug
 
     # Executes each method in a chain one by one
     # @param chain [Array] array of methods to execute
+    # @used_in {#create}
+    # @used_in {#update}
+    # @used_in {#destroy}
+    # @used_in {#show}
+    # @used_in {#index}
     def run_chain(chain)
       chain.each do |action|
         self.send(action)

data/lib/resting_pug/base.rb

@@ -6,6 +6,7 @@ require_relative './params'
 require_relative './modificators'
 require 'will_paginate/active_record'
 
+# A simple and fully customizable way to create an API in your Rails application
 module RestingPug
   # Main module
   module Base

data/lib/resting_pug/chains.rb

@@ -9,6 +9,16 @@ module RestingPug
     # @used_in {Actions#create}
     # @use {Subject#create_subject}
     # @use {Render#decide_what_to_render}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a create chain adding logging to the end
+    #     def create_chain
+    #       super + [:log_creating_subject]
+    #     end
+    #   end
     def create_chain
       [:create_subject, :decide_what_to_render]
     end
@@ -19,6 +29,16 @@ module RestingPug
     # @use {Subject#fetch_subject}
     # @use {Subject#update_subject}
     # @use {Render#decide_what_to_render}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override an update chain adding logging to the end
+    #     def update_chain
+    #       super + [:log_updating_subject]
+    #     end
+    #   end
     def update_chain
       [:fetch_subject, :update_subject, :decide_what_to_render]
     end
@@ -28,6 +48,16 @@ module RestingPug
     # @used_in {Actions#destroy}
     # @use {Subject#fetch_subject}
     # @use {Subject#destroy_subject}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a destroy chain adding logging to the end
+    #     def destroy_chain
+    #       super + [:log_destroying_subject]
+    #     end
+    #   end
     def destroy_chain
       [:fetch_subject, :destroy_subject]
     end
@@ -37,6 +67,16 @@ module RestingPug
     # @used_in {Actions#show}
     # @use {Subject#fetch_subject}
     # @use {Render#render_subject}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a show chain adding logging to the end
+    #     def show_chain
+    #       super + [:log_showing_subject]
+    #     end
+    #   end
     def show_chain
       [:fetch_subject, :render_subject]
     end
@@ -49,6 +89,16 @@ module RestingPug
     # @use {Modificators#sort_subjects}
     # @use {Modificators#paginate_subjects}
     # @use {Render#render_subjects}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override an index chain adding logging to the end
+    #     def index_chain
+    #       super + [:log_indexing_subjects]
+    #     end
+    #   end
     def index_chain
       [:fetch_subjects, :filter_subjects, :sort_subjects, :paginate_subjects, :render_subjects]
     end

data/lib/resting_pug/modificators.rb

@@ -8,6 +8,16 @@ module RestingPug
     # @note Override this method to change pagination of subjects
     # @used_in {Chains#index_chain}
     # @use {Params#pagination_params}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a paginate_subjects method to use kaminari instead of will_paginate
+    #     def paginate_subjects
+    #       @subjects = @subjects.page(pagination_params[:page]).per(pagination_params[:per_page])
+    #     end
+    #   end
     def paginate_subjects
       @subjects = @subjects.paginate(page: pagination_params[:page], per_page: pagination_params[:per_page])
     end
@@ -16,6 +26,16 @@ module RestingPug
     # @note Override this method to change sorting of subjects
     # @used_in {Chains#index_chain}
     # @use {Params#sort_params}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a sort_subjects method to remove default ordering beforehand.
+    #     def sort_subjects
+    #       @subjects = @subjects.reorder(nil).order(sort_params)
+    #     end
+    #   end
     def sort_subjects
       @subjects = @subjects.order(sort_params)
     end
@@ -23,7 +43,17 @@ module RestingPug
     # Filters subjects using filter params
     # @note Override this method to change how subjects are filtered
     # @used_in {Chains#index_chain}
-    # @use {Params#pagination_params}
+    # @use {Params#filter_params}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a filter_subjects method to remove default scope beforehand.
+    #     def filter_subjects
+    #       @subjects = @subjects.unscoped.where(filter_params)
+    #     end
+    #   end
     def filter_subjects
       @subjects = @subjects.where(filter_params)
     end

data/lib/resting_pug/params.rb

@@ -8,50 +8,95 @@ module RestingPug
 
     # Returns an array with all fields that API can use
     # @note Override this method to add or remove fields that you don't want API to use.
-    # @return [Array] of symbols representing attributes
     # @used_in {#permitted_fields_for_show}
     # @used_in {#permitted_fields_for_create}
     # @used_in {#permitted_fields_for_update}
     # @used_in {#permitted_fields_for_sort}
     # @used_in {#permitted_fields_for_filter}
     # @use {Subject#subject_model}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a permitted_fields method to use only :id and :title
+    #     def permitted_fields
+    #       [:id, :title]
+    #     end
+    #   end
     def permitted_fields
       subject_model.column_names.map(&:to_sym)
     end
 
     # Returns an array with all fields that API will show
     # @note Override this method to add or remove fields that you don't want API to show.
-    # @return [Array] of symbols representing attributes
     # @used_in {Render#render_subject}
     # @used_in {Render#render_subjects}
     # @use {#permitted_fields}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a permitted_fields_for_show method to show every permitted attribute except :title
+    #     def permitted_fields_for_show
+    #       permitted_fields - [:title]
+    #     end
+    #   end
     def permitted_fields_for_show
       permitted_fields
     end
 
     # Returns an array with all fields that API will allow to use while creating a subject
     # @note Override this method to add or remove fields that you don't want API to use for creating.
-    # @return [Array] of symbols representing attributes
     # @used_in {#params_for_create}
     # @use {#permitted_fields}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a permitted_fields_for_create method to use every permitted attribute except :title
+    #     def permitted_fields_for_create
+    #       permitted_fields - [:title]
+    #     end
+    #   end
     def permitted_fields_for_create
       permitted_fields - [:id, :created_at, :updated_at]
     end
 
     # Returns an array with all fields that API will allow to use while updating a subject
     # @note Override this method to add or remove fields that you don't want API to use for updating.
-    # @return [Array] of symbols representing attributes
     # @used_in {#params_for_update}
     # @use {#permitted_fields}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a permitted_fields_for_update method to use every permitted attribute except :title
+    #     def permitted_fields_for_update
+    #       permitted_fields - [:title]
+    #     end
+    #   end
     def permitted_fields_for_update
       permitted_fields - [:id, :created_at, :updated_at]
     end
 
     # Returns an array with all fields that API will allow to use while sorting subjects
     # @note Override this method to add or remove fields that you don't want API to use for sorting.
-    # @return [Array] of symbols representing attributes
     # @used_in {#sort_params}
     # @use {#permitted_fields}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a permitted_fields_for_sort method to use every permitted attribute except :title
+    #     def permitted_fields_for_sort
+    #       permitted_fields - [:title]
+    #     end
+    #   end
     def permitted_fields_for_sort
       permitted_fields
     end
@@ -59,10 +104,19 @@ module RestingPug
     # Returns an array with all fields that API will allow to use while filtering subjects by single value
     # @note Override this method to add or remove fields that you don't want API to use for filtering by single value.
     #   If you want to change attributes that can be filtered by arrays of values check {#permitted_fields_for_filter_arrays}
-    # @return [Array] of symbols representing attributes
     # @used_in {#permitted_fields_for_filter_arrays}
     # @used_in {#permitted_fields_for_filter_with_arrays}
     # @use {#permitted_fields}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a permitted_fields_for_sort method to use every permitted attribute except :title
+    #     def permitted_fields_for_sort
+    #       permitted_fields - [:title]
+    #     end
+    #   end
     def permitted_fields_for_filter
       permitted_fields - [:created_at, :updated_at]
     end
@@ -70,16 +124,24 @@ module RestingPug
     # Returns an array with all fields that API will allow to use while filtering subjects by array of values
     # @note Override this method to add or remove fields that you don't want API to use for filtering by array of values.
     #   If you want to change attributes that can be filtered by single value check {#permitted_fields_for_filter}
-    # @return [Array] of symbols representing attributes
     # @used_in {#permitted_fields_for_filter_with_arrays}
     # @use {#permitted_fields_for_filter}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a permitted_fields_for_filter_arrays method to use only :id and :title
+    #     def permitted_fields_for_filter_arrays
+    #       { id: [], title: []}
+    #     end
+    #   end
     def permitted_fields_for_filter_arrays
       permitted_fields_for_filter.map { |field| { field => [] } }
     end
 
     # Returns an array with all fields that API will allow to use while filtering subjects both by single values and by array of values
     # @note To set fields that can be used check {#permitted_fields_for_filter} and {#permitted_fields_for_filter_arrays}
-    # @return [Array] of symbols representing attributes
     # @used_in {#filter_params}
     # @use {#permitted_fields_for_filter}
     # @use {#permitted_fields_for_filter_arrays}
@@ -90,8 +152,8 @@ module RestingPug
     # PARAMS
 
     # Returns strong parameters which are used in creating action
-    # @note Override {#permitted_fields_for_create} to set allowed fields.
-    #   Override {Subject#subject_model_sym} to change the root attrubute of params.
+    # @note Override {#permitted_fields_for_create permitted_fields_for_create} to set allowed fields.
+    #   Override {Subject#subject_model_sym subject_model_sym} to change the root attrubute of params.
     # @see http://guides.rubyonrails.org/action_controller_overview.html#strong-parameters
     # @used_in {Subject#create_subject}
     # @use {Subject#subject_model_sym}
@@ -101,8 +163,8 @@ module RestingPug
     end
 
     # Returns strong parameters which are used in updating action
-    # @note Override {#permitted_fields_for_update} to set allowed fields.
-    #   Override {Subject#subject_model_sym} to change the root attrubute of params.
+    # @note Override {#permitted_fields_for_update permitted_fields_for_update} to set allowed fields.
+    #   Override {Subject#subject_model_sym subject_model_sym} to change the root attrubute of params.
     # @see http://guides.rubyonrails.org/action_controller_overview.html#strong-parameters
     # @used_in {Subject#update_subject}
     # @use {Subject#subject_model_sym}
@@ -114,7 +176,7 @@ module RestingPug
     # FILTERING
 
     # Returns strong parameters which are used for filtering subjects
-    # @note Override {#permitted_fields_for_filter} and {permitted_fields_for_filter_arrays} to set allowed fields.
+    # @note Override {#permitted_fields_for_filter permitted_fields_for_filter} and {#permitted_fields_for_filter_arrays permitted_fields_for_filter_arrays} to set allowed fields.
     # @see http://guides.rubyonrails.org/action_controller_overview.html#strong-parameters
     # @used_in {Modificators#filter_subjects}
     # @use {#permitted_fields_for_filter_with_arrays}
@@ -125,8 +187,8 @@ module RestingPug
     # SORT
 
     # Transforms a string like "-id,name" to a hash { id: :desc, name: :asc }
-    # @note Override {#permitted_fields_for_sort} to set allowed fields to sort.
-    #   Override {#default_sort_params} to set default sort params.
+    # @note Override {#permitted_fields_for_sort permitted_fields_for_sort} to set allowed fields to sort.
+    #   Override {#default_sort_params default_sort_params} to set default sort params.
     # @used_in {Modificators#sort_subjects}
     # @use {#permitted_fields_for_sort}
     # @use {#default_sort_params}
@@ -151,9 +213,19 @@ module RestingPug
     end
 
     # Returns a hash with default sorting params
-    # @note Override {#permitted_fields_for_sort} to set allowed fields to sort.
+    # @note Override {#permitted_fields_for_sort permitted_fields_for_sort} to set allowed fields to sort.
     # @see http://guides.rubyonrails.org/active_record_querying.html#ordering
     # @used_in {#sort_params}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a default_sort_params to set default sorting to sorted descending by title
+    #     def default_sort_params
+    #       { title: :desc }
+    #     end
+    #   end
     def default_sort_params
       {id: :desc}
     end
@@ -161,8 +233,8 @@ module RestingPug
     # PAGINATION
 
     # Handles pagination params and return a hash like { page: 1, per_page: 10 }
-    # @note Override {#per_page_range} to set minimum and maximum per_page param.
-    #   Override {#per_page_default} to set default per_page param.
+    # @note Override {#per_page_range per_page_range} to set minimum and maximum per_page param.
+    #   Override {#per_page_default per_page_default} to set default per_page param.
     # @used_in {Modificators#paginate_subjects}
     # @use {#per_page_range}
     # @use {#per_page_default}
@@ -172,18 +244,38 @@ module RestingPug
       return { page: page, per_page: per_page }
     end
 
-    # Returns a hash minimum and maximum per_page param like { page: 1, per_page: 10 }
-    # @note Override {#per_page_default} to set default per_page param.
+    # Returns a hash with minimum and maximum per_page param like { page: 1, per_page: 10 }
+    # @note Override {#per_page_default per_page_default} to set default per_page param.
     # @used_in {#pagination_params}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a per_page_range to set minimum possible value for per_page 10 and maximum 20
+    #     def per_page_range
+    #       { min: 10, max: 20 }
+    #     end
+    #   end
     def per_page_range
       { min: 5, max: 100 }
     end
 
     # Returns a default per_page param
-    # @note Override {#per_page_range} to set minimum and maximum per_page param
+    # @note Override {#per_page_range per_page_range} to set minimum and maximum per_page param
     # @used_in {#pagination_params}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a per_page_default to set default page size to 15
+    #     def per_page_default
+    #       15
+    #     end
+    #   end
     def per_page_default
       10
     end
   end
-end
+end

data/lib/resting_pug/render.rb

@@ -5,11 +5,25 @@ module RestingPug
     protected
 
     # Calls {#render_subject} if subject is valid and {#render_errors} otherwise
-    # @note Override {#render_subject} and {#render_errors} to change rendering behaviour
+    # @note Override {#render_subject render_subject} and {#render_errors render_errors} to change rendering behaviour
     # @used_in {Chains#create_chain}
     # @used_in {Chains#update_chain}
     # @use {#render_subject}
     # @use {#render_errors}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a decide_what_to_render to render something special if @subject id is 3
+    #     def decide_what_to_render
+    #       if @subject.valid?
+    #         @subject.id == 3 ? render_something_special : render_subject
+    #       else
+    #         render_errors
+    #       end
+    #     end
+    #   end
     def decide_what_to_render
       if @subject.valid?
         render_subject
@@ -20,23 +34,43 @@ module RestingPug
 
     # Renders json with a subject
     # @note Override this method to add more complicated logic of rendering.
-    #   Override {Subject#subject_model_sym} to change root attribute.
-    #   Override {Params#permitted_fields_for_show} to change shown attributes.
+    #   Override {Subject#subject_model_sym subject_model_sym} to change root attribute.
+    #   Override {Params#permitted_fields_for_show permitted_fields_for_show} to change shown attributes.
     # @used_in {#decide_what_to_render}
     # @used_in {Chains#show_chain}
     # @use {Subject#subject_model_sym}
     # @use {Params#permitted_fields_for_show}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a render_subject to render without a root object
+    #     def render_subject
+    #       render json: @subject.as_json(only: permitted_fields_for_show)
+    #     end
+    #   end
     def render_subject
       render json: { subject_model_sym => @subject.as_json(only: permitted_fields_for_show) }
     end
 
     # Renders json with subjects
     # @note Override this method to add more complicated logic of rendering.
-    #   Override {Subject#subject_model_sym_plural} to change root attribute.
-    #   Override {Params#permitted_fields_for_show} to change shown attributes.
+    #   Override {Subject#subject_model_sym_plural subject_model_sym_plural} to change root attribute.
+    #   Override {Params#permitted_fields_for_show permitted_fields_for_show} to change shown attributes.
     # @used_in {Chains#index_chain}
     # @use {Subject#subject_model_sym_plural}
     # @use {Params#permitted_fields_for_show}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a render_subjects to render with 'items' as a root object
+    #     def render_subjects
+    #       render json: { items: @subjects.as_json(only: permitted_fields_for_show) }
+    #     end
+    #   end
     def render_subjects
       render json: { subject_model_sym_plural => @subjects.as_json(only: permitted_fields_for_show) }
     end
@@ -44,6 +78,16 @@ module RestingPug
     # Renders empty response
     # @note Override this method to add more complicated logic of rendering.
     # @used_in {Subject#destroy_subject}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a render_nothing to render with status 200
+    #     def render_nothing
+    #       render json: {}, status: 200
+    #     end
+    #   end
     def render_nothing
       render json: {}, status: 204
     end
@@ -51,6 +95,16 @@ module RestingPug
     # Renders errors
     # @note Override this method to add more complicated logic of rendering.
     # @used_in {#decide_what_to_render}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a render_errors to render with status 400
+    #     def render_errors
+    #       render json: { errors: @subject.errors }, status: 400
+    #     end
+    #   end
     def render_errors
       render json: { errors: @subject.errors }, status: 422
     end
@@ -58,15 +112,35 @@ module RestingPug
     # Renders error when required params are missing
     # @note Override this method to add more complicated logic of rendering.
     # @used_in {Base.included}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a render_param_missing to render with status 422
+    #     def render_param_missing
+    #       render json: { errors: { subject_model_sym => ['param is missing'] } }, status: 422
+    #     end
+    #   end
     def render_param_missing
       render json: { errors: { subject_model_sym => ['param is missing'] } }, status: 400
     end
 
-    # Renders error when required params are missing
+    # Renders error when required object is not found
     # @note Override this method to add more complicated logic of rendering.
     # @used_in {Base.included}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a render_not_found to render with message 'Not found'
+    #     def render_not_found
+    #       render json: { message: 'Not found' }, status: 404
+    #     end
+    #   end
     def render_not_found
       render json: {}, status: 404
     end
   end
-end
+end

data/lib/resting_pug/subject.rb

@@ -12,6 +12,16 @@ module RestingPug
     # @used_in {#fetch_subject}
     # @used_in {#fetch_subjects}
     # @used_in {Params#permitted_fields}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a subject_model to use Novel as a model
+    #     def subject_model
+    #       Novel
+    #     end
+    #   end
     def subject_model
       controller_name.classify.constantize
     end
@@ -23,6 +33,16 @@ module RestingPug
     # @used_in {Params#params_for_update}
     # @used_in {Render#render_subject}
     # @used_in {Render#render_param_missing}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a subject_model to use :novel as a symbol used in params and rendering
+    #     def subject_model_sym
+    #       :novel
+    #     end
+    #   end
     def subject_model_sym
       subject_model.to_s.underscore.to_sym
     end
@@ -31,6 +51,16 @@ module RestingPug
     # @note Override this method to get another root JSON response.
     # @use {#subject_model}
     # @used_in {Render#render_subjects}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a subject_model_sym_plural to use :novels as a symbol used in index action
+    #     def subject_model_sym_plural
+    #       :novels
+    #     end
+    #   end
     def subject_model_sym_plural
       subject_model.to_s.pluralize.underscore.to_sym
     end
@@ -40,6 +70,16 @@ module RestingPug
     # @used_in {Chains#create_chain}
     # @use {#subject_model}
     # @use {Params#params_for_create}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a create_subject to create only if title is not 'None'
+    #     def create_subject
+    #       @subject = subject_model.create(params_for_create) unless params_for_create[:title] == 'None'
+    #     end
+    #   end
     def create_subject
       @subject = subject_model.create(params_for_create)
     end
@@ -48,6 +88,16 @@ module RestingPug
     # @note Override this method to add some custom logic to updating process.
     # @used_in {Chains#update_chain}
     # @use {Params#params_for_update}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a update_subject to update only if title is not 'None'
+    #     def update_subject
+    #       @subject.update(params_for_update) unless params_for_update[:title] == 'None'
+    #     end
+    #   end
     def update_subject
       @subject.update(params_for_update)
     end
@@ -57,6 +107,20 @@ module RestingPug
     # @used_in {Chains#destroy_chain}
     # @use {Render#render_nothing}
     # @use {Render#render_errors}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a destroy_subject to destroy only if title is not 'None'
+    #     def destroy_subject
+    #       if @subject.title != 'None' && @subject.destroy
+    #         render_nothing
+    #       else
+    #         render_errors
+    #       end
+    #     end
+    #   end
     def destroy_subject
       if @subject.destroy
         render_nothing
@@ -72,6 +136,16 @@ module RestingPug
     # @used_in {Chains#destroy_chain}
     # @used_in {Chains#show_chain}
     # @use {#subject_model}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a fetch_subject to return a default subject if requested is not found
+    #     def fetch_subject
+    #       @subject = subject_model.find_by_id(params[:id]) || default_subject
+    #     end
+    #   end
     def fetch_subject
       @subject = subject_model.find(params[:id])
     end
@@ -80,6 +154,16 @@ module RestingPug
     # @note Override this method to add some custom logic to fetching process.
     # @used_in {Chains#index_chain}
     # @use {#subject_model}
+    # @example
+    #   class BooksController < ApplicationController
+    #     include RestingPug::Base
+    #
+    #     private
+    #     # Override a fetch_subjects to return subject where title is not 'None'
+    #     def fetch_subjects
+    #       @subjects = subject_model.where.not(title: 'None')
+    #     end
+    #   end
     def fetch_subjects
       @subjects = subject_model.all
     end

data/lib/resting_pug/version.rb

@@ -1,3 +1,4 @@
 module RestingPug
-  VERSION = '0.1.0'
+  # Actual version
+  VERSION = '0.1.1'
 end

metadata

@@ -1,27 +1,27 @@
 --- !ruby/object:Gem::Specification
 name: resting_pug
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Slava Korolev
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-11-02 00:00:00.000000000 Z
+date: 2017-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: will_paginate
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '3'
 - !ruby/object:Gem::Dependency
@@ -108,6 +108,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: codecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Resting Pug allows you to create a JSON API with just adding one line
   to your controller and fully customize it with overriding small and simple helper
   methods.