rest-api-generator 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5f141a24ca9cc9e364aec03cdcf46eb3e2bee8cb36cbc120b8034c8ca7fad52
-  data.tar.gz: 6f6410abc9657e49c10cd9a9654a0e59360128aa1990a7acdbde26485ce9806f
+  metadata.gz: cf4062a70bed1e9006d96375d4110b3918f3bf5d074304c4619abfa4fe33eb03
+  data.tar.gz: ba52d11b288dd8004e68327a8db4aabac8bef8be93eea85382f3bf349406ea39
 SHA512:
-  metadata.gz: 5130c55d992d388cb807642b0680983ef9fbf023d930d4182ff4af257c7209edb9dead5d4322d0d32a8eedc4b1d9e05a084d04c7735ac471c27ff34c4f984a63
-  data.tar.gz: 4172cf89cbff2f8ddc5216f174066fa1ccac17f7462b697103be6e624b0acd94c3114e84e96b4891dd6a6aa9151dfcb078030f6cbe23f84ed605c90f8eba6e98
+  metadata.gz: a1ef3d60ca714e5edf5db7cdcf6b0287ef22c2123c907070cb3b6608ca159ceba200642a8b45894cb88e0fab73d5abaeb728e19a05c9e2760cd0e17ccb155732
+  data.tar.gz: 9849fa88d3b3a9f5a070c7f4a4ca29fc3deb8447adb80260004aa68076cd0a27db9cbeb5d214aed2505df4a1c1a48e26378dc41b6626159eb635d1a7d2c0218e

data/Gemfile

@@ -9,4 +9,4 @@ gem "rake", "~> 13.0"
 
 gem "rspec", "~> 3.0"
 
-gem "rubocop", "~> 1.21"
+gem "switchcop"

data/Gemfile.lock

@@ -1,107 +1,234 @@
 PATH
   remote: .
   specs:
-    rest-api-generator (0.1.0)
-      railties (>= 5.0.0)
+    rest-api-generator (0.1.2)
+      rails (>= 5.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    actionpack (7.0.2.4)
-      actionview (= 7.0.2.4)
-      activesupport (= 7.0.2.4)
+    actioncable (7.0.4)
+      actionpack (= 7.0.4)
+      activesupport (= 7.0.4)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+    actionmailbox (7.0.4)
+      actionpack (= 7.0.4)
+      activejob (= 7.0.4)
+      activerecord (= 7.0.4)
+      activestorage (= 7.0.4)
+      activesupport (= 7.0.4)
+      mail (>= 2.7.1)
+      net-imap
+      net-pop
+      net-smtp
+    actionmailer (7.0.4)
+      actionpack (= 7.0.4)
+      actionview (= 7.0.4)
+      activejob (= 7.0.4)
+      activesupport (= 7.0.4)
+      mail (~> 2.5, >= 2.5.4)
+      net-imap
+      net-pop
+      net-smtp
+      rails-dom-testing (~> 2.0)
+    actionpack (7.0.4)
+      actionview (= 7.0.4)
+      activesupport (= 7.0.4)
       rack (~> 2.0, >= 2.2.0)
       rack-test (>= 0.6.3)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.0, >= 1.2.0)
-    actionview (7.0.2.4)
-      activesupport (= 7.0.2.4)
+    actiontext (7.0.4)
+      actionpack (= 7.0.4)
+      activerecord (= 7.0.4)
+      activestorage (= 7.0.4)
+      activesupport (= 7.0.4)
+      globalid (>= 0.6.0)
+      nokogiri (>= 1.8.5)
+    actionview (7.0.4)
+      activesupport (= 7.0.4)
       builder (~> 3.1)
       erubi (~> 1.4)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.1, >= 1.2.0)
-    activesupport (7.0.2.4)
+    activejob (7.0.4)
+      activesupport (= 7.0.4)
+      globalid (>= 0.3.6)
+    activemodel (7.0.4)
+      activesupport (= 7.0.4)
+    activerecord (7.0.4)
+      activemodel (= 7.0.4)
+      activesupport (= 7.0.4)
+    activestorage (7.0.4)
+      actionpack (= 7.0.4)
+      activejob (= 7.0.4)
+      activerecord (= 7.0.4)
+      activesupport (= 7.0.4)
+      marcel (~> 1.0)
+      mini_mime (>= 1.1.0)
+    activesupport (7.0.4)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
       tzinfo (~> 2.0)
+    ammeter (1.1.5)
+      activesupport (>= 3.0)
+      railties (>= 3.0)
+      rspec-rails (>= 2.2)
     ast (2.4.2)
     builder (3.2.4)
     concurrent-ruby (1.1.10)
     crass (1.0.6)
+    database_cleaner (2.0.1)
+      database_cleaner-active_record (~> 2.0.0)
+    database_cleaner-active_record (2.0.1)
+      activerecord (>= 5.a)
+      database_cleaner-core (~> 2.0.0)
+    database_cleaner-core (2.0.1)
+    date (3.3.3)
     diff-lcs (1.5.0)
-    erubi (1.10.0)
-    i18n (1.10.0)
+    erubi (1.12.0)
+    globalid (1.0.0)
+      activesupport (>= 5.0)
+    i18n (1.12.0)
       concurrent-ruby (~> 1.0)
-    loofah (2.17.0)
+    json (2.6.3)
+    loofah (2.19.1)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
+    mail (2.8.0)
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    marcel (1.0.2)
     method_source (1.0.0)
-    minitest (5.15.0)
-    nokogiri (1.13.5-x86_64-linux)
+    mini_mime (1.1.2)
+    minitest (5.16.3)
+    net-imap (0.3.4)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.1)
+      timeout
+    net-smtp (0.3.3)
+      net-protocol
+    nio4r (2.5.8)
+    nokogiri (1.13.10-x86_64-linux)
       racc (~> 1.4)
     parallel (1.22.1)
-    parser (3.1.2.0)
+    parser (3.1.3.0)
       ast (~> 2.4.1)
-    racc (1.6.0)
-    rack (2.2.3)
-    rack-test (1.1.0)
-      rack (>= 1.0, < 3)
+    racc (1.6.2)
+    rack (2.2.4)
+    rack-test (2.0.2)
+      rack (>= 1.3)
+    rails (7.0.4)
+      actioncable (= 7.0.4)
+      actionmailbox (= 7.0.4)
+      actionmailer (= 7.0.4)
+      actionpack (= 7.0.4)
+      actiontext (= 7.0.4)
+      actionview (= 7.0.4)
+      activejob (= 7.0.4)
+      activemodel (= 7.0.4)
+      activerecord (= 7.0.4)
+      activestorage (= 7.0.4)
+      activesupport (= 7.0.4)
+      bundler (>= 1.15.0)
+      railties (= 7.0.4)
     rails-dom-testing (2.0.3)
       activesupport (>= 4.2.0)
       nokogiri (>= 1.6)
-    rails-html-sanitizer (1.4.2)
-      loofah (~> 2.3)
-    railties (7.0.2.4)
-      actionpack (= 7.0.2.4)
-      activesupport (= 7.0.2.4)
+    rails-html-sanitizer (1.4.4)
+      loofah (~> 2.19, >= 2.19.1)
+    railties (7.0.4)
+      actionpack (= 7.0.4)
+      activesupport (= 7.0.4)
       method_source
       rake (>= 12.2)
       thor (~> 1.0)
       zeitwerk (~> 2.5)
     rainbow (3.1.1)
     rake (13.0.6)
-    regexp_parser (2.3.1)
+    regexp_parser (2.6.1)
     rexml (3.2.5)
-    rspec (3.11.0)
-      rspec-core (~> 3.11.0)
-      rspec-expectations (~> 3.11.0)
-      rspec-mocks (~> 3.11.0)
-    rspec-core (3.11.0)
-      rspec-support (~> 3.11.0)
-    rspec-expectations (3.11.0)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.0)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.1)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
-    rspec-mocks (3.11.1)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.1)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
-    rspec-support (3.11.0)
-    rubocop (1.28.2)
+      rspec-support (~> 3.12.0)
+    rspec-rails (6.0.1)
+      actionpack (>= 6.1)
+      activesupport (>= 6.1)
+      railties (>= 6.1)
+      rspec-core (~> 3.11)
+      rspec-expectations (~> 3.11)
+      rspec-mocks (~> 3.11)
+      rspec-support (~> 3.11)
+    rspec-support (3.12.0)
+    rubocop (1.40.0)
+      json (~> 2.3)
       parallel (~> 1.10)
-      parser (>= 3.1.0.0)
+      parser (>= 3.1.2.1)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
-      rexml
-      rubocop-ast (>= 1.17.0, < 2.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.23.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.17.0)
+    rubocop-ast (1.24.0)
       parser (>= 3.1.1.0)
+    rubocop-performance (1.15.2)
+      rubocop (>= 1.7.0, < 2.0)
+      rubocop-ast (>= 0.4.0)
+    rubocop-rails (2.17.4)
+      activesupport (>= 4.2.0)
+      rack (>= 1.1)
+      rubocop (>= 1.33.0, < 2.0)
+    rubocop-rspec (2.16.0)
+      rubocop (~> 1.33)
+    rubocop-shopify (2.10.1)
+      rubocop (~> 1.35)
     ruby-progressbar (1.11.0)
+    sqlite3 (1.5.4-x86_64-linux)
+    switchcop (0.1.2)
+      rubocop (~> 1.40.0)
+      rubocop-performance (~> 1.15.1)
+      rubocop-rails (~> 2.17.3)
+      rubocop-rspec (~> 2.16.0)
+      rubocop-shopify (~> 2.10.1)
     thor (1.2.1)
-    tzinfo (2.0.4)
+    timeout (0.3.1)
+    tzinfo (2.0.5)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (2.1.0)
-    zeitwerk (2.5.4)
+    unicode-display_width (2.3.0)
+    websocket-driver (0.7.5)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.6.6)
 
 PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  ammeter (~> 1.1.5)
+  database_cleaner
   rake (~> 13.0)
   rest-api-generator!
   rspec (~> 3.0)
-  rubocop (~> 1.21)
+  rspec-rails (~> 6.0.0)
+  sqlite3
+  switchcop
 
 BUNDLED WITH
    2.3.3

data/README.md

@@ -1,23 +1,46 @@
-# RestApiGenerator
+# rest-api-generator
 
-This gem works as a scaffold to generate an endpoint, it generates:
+This gem helps you to build a Ruby on Rails REST API faster, using a scaffold-like generator that follows the best
+practices.
 
-<ul>
-    <li> Model </li>
-    <li> Migration </li>
-    <li> Routes (resource) </li>
-    <li> Controller </li>
-    <li> Spec test of controller </li>
-    <li> Factory bot </li>
-</ul>
+## How it works?
+
+The gems use vanilla Rails generators in combination with our templates to create all the resources needed to build a
+REST API.
+
+Following [Switch Dreams's](https://www.switchdreams.com.br/]) coding practices, the controllers are built with:
+
+- We use an error module to centralize error handling, rescuing from a custom and some of ActiveRecord exceptions.
+  The inspiration for this strategy was
+  this [article](https://medium.com/rails-ember-beyond/error-handling-in-rails-the-modular-way-9afcddd2fe1b.)
 
-the commnad its simmilar to the model generator "rails g model model_name attributes", in fact it invokes this generator to genrate the model and migration file
+- For tests, we use RSpec and FactoryBot.
+
+## Current Features
+
+- [Automatic rest api crud generation](#example)
+- [Nested Resource](#nested-resource)
+- [Modular error handler](#modular-error-handler)
+- [Resource ordering](#ordering)
+- [Resource filter](#filtering)
+
+## Next Features
+
+- Generate nested resource end-points 🚧
+- Automated documentation 🚧 https://github.com/SwitchDreams/rest-api-generator/issues/12
+- Serialization https://github.com/SwitchDreams/rest-api-generator/issues/14
+  https://github.com/SwitchDreams/rest-api-generator/issues/11
+- Pagination https://github.com/SwitchDreams/rest-api-generator/issues/15
+- Integration with AVO
+- Select fields
+- User auth module
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
+# Build a Ruby on Rails REST API faster
 gem 'rest-api-generator'
 ```
 
@@ -30,92 +53,237 @@ Or install it yourself as:
     $ gem install rest-api-generator
 
 ## Requirements
-You need to have installed in your application rspec and factory bot
+
+1. You need to have installed RSpec and FactoryBot in your application.
 
 <ul>
-  <li>Rspec: https://github.com/rspec/rspec-rails</li>
+  <li>RSpec: https://github.com/rspec/rspec-rails</li>
   <li>Factory bot: https://github.com/thoughtbot/factory_bot_rails</li>
 </ul>
 
-then inside your folder app/spec create a new folder called "requests", that's where your tests will be generated
+2. Include in ApplicationController the error handler module:
+
+```ruby
+
+class ApplicationController < ActionController::API
+  include RestApiGenerator::ErrorHandler
+end
+```
+
+This error handler will rescue from: `ActiveRecord::RecordNotFound`
+, `ActiveRecord::ActiveRecordError`, `ActiveRecord::RecordInvalid`, `ActiveModel::ValidationError`
+, `RestApiGenerator::CustomError`.
 
 ## Usage
-### Run command
-   $ rails g generator table_name attributes
 
-************************************************************************************
-#### Model
-this will generate a table and a migration with the table name and it's attribute, it invokes the model generator
+### Generate Resource
 
-************************************************************************************
-#### Endpoint
-It will genrate a controller CarsController that has the methods
+```bash
+$ rails g rest_api_generator:resource table_name attributes
+```
 
-##### Create
-saves instance of generated model to database and return json of instance with status ok
+This command will create:
 
-##### Update
-updates instance of generated modelfrom database and return json of instance with status ok
+- **Model and Migration**: Using rails default model generator
+- **Controller**: A controller that implementes CRUD by inheritance of `RestApiGenerator::ResourceController`, or you
+  can use eject option for create a controller
+  that implements index, show, create, update and destroy methods.
+- **Specs for the created controller**
+- **Factory bot factory for created model**
+- **Routes**: with rails resources
 
-##### Delete
-deletes instance of generated model from database 
+### Example
 
-##### Show
-returns JSON instance of generated model from database with status ok
+```bash
+$ rails g rest_api_generator:resource car name:string color:string
+```
 
-##### Index
-returns JSON instance of generated model from database with status ok
+Will generate following controller and the other files:
 
+```ruby
+# app/controllers/cars_controller.rb
+class CarsController < RestApiGenerator::ResourceController
+end
+```
 
-create and update will have permitted params defined by the attributes defined in the command (except if the attribute is type reference)
-************************************************************************************
-### Spec
+For a better experience you can override some methods from the
+[default controller](https://github.com/SwitchDreams/rest-api-generator/blob/main/lib/rest_api_generator/resource_controller.rb)
 
-##### Create
-checks if instance was saved in database
+### Options
 
-##### Update
-checks if instance was updated in database ok
+| Option | Goal                                                         | Default | Usage Example   |
+|--------|--------------------------------------------------------------|---------|-----------------|
+| father | Generate nested resource                                     | nil     | --father Users  |
+| scope  | Scope the resource for other route or namespace organization | nil     | --scope Api::V1 |
+| eject  | Eject the controller to high customization                   | false   | true            |
 
-##### Delete
-checks if instance was deleted from database
+#### Scope
 
-##### Show
-check if status ok
+In REST api one of the best practices is versioning the end-points, and you can achieve this using scope options,
+example:
 
-##### Index
-check if status ok 
+```bash
+# Command
+rails g rest_api_generator:resource car name:string color:string --scope Api::V1
+```
+
+```ruby
+# GET api/v1/cars
+module Api::V1
+  class CarsController < RestApiGenerator::ResourceController
+  end
+end
+```
+
+For this option you need to manually setup routes, for this example:
+
+```ruby
+# routes.rb
+namespace :api do
+  namespace :v1 do
+    resources :cars
+  end
+end
+```
+
+#### Nested resource
 
-************************************************************************************
-### Factory
-The factory will be generated with it's custom generator, defined in the instalation of the factory-bot
+In REST api sometimes we need to build a nested resource, for example when we need to get all devices from a user, for
+this we have nested resource option:
+
+```bash
+# Command
+rails g rest_api_generator:resource Devices name:string color:string users:references --scope Users
+```
+
+```ruby
+# GET users/:user_id/devices
+module Users
+  class DevicesController < RestApiGenerator::ChildResourceController
+  end
+end
+```
+
+For this option you need to manually setup routes, for this example:
+
+```ruby
+# routes.rb
+resources :users do
+  resources :devices, controller: 'users/devices'
+end
+```
 
-************************************************************************************
-### Routes
-the routes generated are the basic resources routes:
-    table_name: resources
+Considerations:
 
-************************************************************************************
-### Scope
-It's possible to add flag in the command to generate an endpoint with a parent
-   $ rails g generator table_name attributes --scope father_name
+- The children model needs to belongs_to parent model and parent model needs to have has_many children model
 
-the only thing this won't genrate it's the nested routes, but it will generate all the previous files mentioned just liek a scaffold
+#### Eject
+
+Or you can use the `eject` option for create the controller with the implemented methods:
+
+```bash
+rails g rest_api_generator:resource car name:string color:string --eject true
+```
+
+```ruby
+
+class CarsController < ApplicationController
+  before_action :set_car, only: %i[show update destroy]
+
+  def index
+    @car = Car.all
+    render json: @car, status: :ok
+  end
+
+  def show
+    render json: @car, status: :ok
+  end
+
+  def create
+    @car = Car.create!(car_params)
+    render json: @car, status: :created
+  end
+
+  def update
+    @car = Car.update!(car_params)
+    render json: @car, status: :ok
+  end
+
+  def destroy
+    @car.destroy!
+  end
+
+  private
+
+  def set_car
+    @car = Car.find(params[:id])
+  end
+
+  def car_params
+    params.require(:car).permit(:name, :color)
+  end
+end
+```
+
+### Resource Features
+
+#### Modular Error Handler
+
+The error module will return a json in this following format when any active record or custom error raises.
+
+```json
+{
+  "status": 422,
+  "error": "",
+  "message": ""
+}
+```
+
+This is good to padronize the error handler in front-end too.
+
+#### Ordering
+
+For ordering use this format:
+
+- Ordering asc: `GET /cars?sort=+name or GET /cars?sort=name`
+- Ordering desc: `GET /card?sort=-name`
+
+By default, every resource column can be the key for ordering.
+
+#### Filtering
+
+For filter is needed to add some scopes in Model file, example:
+
+```ruby
+# app/models/car.rb
+
+class Car < ApplicationRecord
+  include RestApiGenerator::Filterable
+
+  filter_scope :filter_by_color, ->(color) { where(color: color) }
+  filter_scope :filter_by_name, ->(name) { where("name LIKE ?", "%#{name}%") }
+end
+```
+
+And It's done, you can filter your index end-point:
+
+- `GET /cars?color=blue or GET /cars?color=red&name=Ferrari`
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can
+also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the
+version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version,
+push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/rest-api-generator. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/rest-api-generator/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/SwitchDreams/rest-api-generator. This project
+is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to
+the [code of conduct](https://github.com/SwitchDreams/rest-api-generator/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the Rest::Api::Generator project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/rest-api-generator/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -9,4 +9,4 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: %i[spec rubocop]
+task default: [:spec, :rubocop]

data/lib/generators/rest_api_generator/helpers.rb

@@ -17,5 +17,35 @@ module RestApiGenerator
         Rails::Generators::GeneratedAttribute.new(column.name.to_s, column.type.to_s)
       end
     end
+
+    def option_to_path(option)
+      option.downcase.split("::").join("/")
+    end
+
+    def scope_route_path
+      return "" if options["scope"].blank?
+
+      option_to_path(options["scope"])
+    end
+
+    def nested_routes
+      return "" if options["father"].blank?
+
+      "#{options["father"].downcase.pluralize}/\#{#{options["father"].singularize.downcase}.id}/#{plural_name}"
+    end
+
+    def initial_route
+      scope_route_path + "/" + nested_routes
+    end
+
+    def spec_routes
+      {
+        index: initial_route,
+        show: initial_route + "\#{#{singular_name}.id}",
+        create: initial_route,
+        update: initial_route + "\#{#{singular_name}.id}",
+        delete: initial_route + "\#{#{singular_name}.id}",
+      }
+    end
   end
 end