tramway-api 1.1.0.1 → 1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15a37c45bc7e5c0628296885e619e8081402ec6c2e08dd4667dac931f725e31e
-  data.tar.gz: c7b0d35d1f0e292936b776e9b1f500baf102a324e23a9d3b4d51587150e7c090
+  metadata.gz: 875752ec80bea3a12cdac3f2a3424f777fc0bcf4a94b6c28a5f1c4f98e5a6e34
+  data.tar.gz: ce5f8b2cb550ad0d1a5495ae622152119dc4253dd045fa348fa6921a88751691
 SHA512:
-  metadata.gz: d507ebf4f4134352edd16a64e545ff2572c9a315c401e3ddb238e963d5fbd687c2ef10561de04395c90719264fce26d889229db40c09779a417c60672a830d56
-  data.tar.gz: 7102cbd966ef91bc4a65de1645450af677648cfc5a0923f52a8f69e403d371d0532ab47bbc2cc10fb93a181a3c60ef7b1527e24e7e355782a2bae9d9d544862b
+  metadata.gz: 8b629b1c487b02b054885db26d4e49b97ed652cda40cb4d53e11d25cca170d8d0d876619b13df307cb0a19290d9f7447196dc4f24b5c7962edfad26092a194ff
+  data.tar.gz: 37241c50fc18e27b16fb2c4a2c7eb10ec611b163a046c92cca128a95ca9127950e0e739ddc5ff468890cc40da59bca2d569c04b1d7a8cfac7c24d3baba6fcc86

data/README.md

@@ -1,26 +1,287 @@
 # Tramway::Api
-Short description and motivation.
+
+## English Readme
+
+coming soon...
+
+## Russian Readme
+
+Простой в использовании, легко устанавливаемый и плохо кастомизируемый Rails-engine с готовым CRUD через API.
+
+Принцип работы. В приложении заранее указывается для каких моделей создаётся API CRUD. Идея проекта - возможность быстрой выкатки API, с возможностью в последствии избавиться от Tramway API, когда ваш проект становится сложнее.
+
+Гем НЕ манкипатчит стандартные классы и поведение Rails! Именно по этой причине было решено реализовать как Rails-engine, который в последствии можно просто и легко удалить из проекта.
+
+Фичи:
+
+* готовый CRUD для определённых разработчиком моделей
+* сохранение истории изменений записей (используется гем `audited`)
+* поддержка загрузки файлов (используется `carrierwave`)
+* аутентификация пользователя через JWT (используется `knock`)
+* поддержка по умолчанию JSON API спецификации (через гем `active_model_serializers`)
+* мягкое удаление записей по умолчанию
+* поддержка коммуникации по уникальному uid объектов, чтобы не публиковать ID в базе
+
+Ограничения:
+
+* только с ActiveRecord
+* только с версией Rails 5.1.* (поддержка 5.2 вскоре будет реализована автором гема, поддержка автором Rails 6 начнётся с версии 6.1. По религиозным автор не использует Rails версий *.0.*
+* Ruby >= 2.3
+* все модели, которые будут использованы гемом должны наследоваться от `Tramway::Core::ApplicationRecord`
+* все модели, которые будут использованы гемом должны иметь атрибут `state`, типа `string` или `text`. Этот атрибут нужен для реализации мягкого удаления. Полное удаление записей из базы не поддерживается
+* все модели, которые будут использованы гемом должны иметь атрибут 
+
+Недостатки, которые будут вскоре ликвидированы:
+
+* ядро `tramway-core` подгружает в себя ненужных для API гемов (недостаток не имеет смысла в случае использования вместе с этим решением гема `tramway-admin`):
+  * bootstrap
+  * font_awesome5_rails
+  * haml
+* требуется ручное добавление требуемых для работы гемов
+  ```ruby
+  gem 'active_model_serializers', '0.10.5'
+  gem 'tramway-core'
+  gem 'state_machine', github: 'seuros/state_machine'
+  gem 'knock'
+  ```
 
 ## Usage
-How to use my plugin.
 
-## Installation
-Add this line to your application's Gemfile:
+```
+rails new tramway_api_sample
+```
+
+*Gemfile*
+
+```ruby
+gem 'tramway-api', '>= 1.1.0.1'
+gem 'active_model_serializers', '0.10.5'
+gem 'tramway-core'
+gem 'state_machine', github: 'seuros/state_machine'
+gem 'knock'
+```
+
+Run `bundle install`
+
+Then generate User (you use another name, it's just an example) model
+
+```
+rails g model user email:text password_digest:text username:text state:text uid:text
+```
+
+Add generating uid by default
+
+*db/migrate/create_users_*.rb
+
+```ruby
+t.uuid :uid, default: 'uuid_generate_v4()'
+```
+
+*app/models/user.rb*
+
+```ruby
+class User < Tramway::Core::ApplicationRecord
+  has_secure_password
+end
+```
+
+Create file `config/initializers/tramway.rb`
+
+```ruby
+::Tramway::Api.auth_config = { user_model: User, auth_attributes: %i[email username] }
+::Tramway::Api.set_available_models user: %i[create update]
+```
+
+Run `rails g tramway:core:install`
+
+Run `rails db:create db:migrate`
+
+*config/routes.rb*
+
+```ruby
+Rails.application.routes.draw do
+  mount Tramway::Api::Engine, at: '/api'
+end
+```
+
+Create file *app/forms/user_sign_up_form.rb*
+
+```ruby
+class UserSignUpForm < Tramway::Core::ApplicationForm
+  properties :username, :email, :password
+end
+```
+
+**DONE!**
+
+## Testing
+
+# Preparation (optional)
+
+Let's write RSpec test to check what we have:
+
+*Gemfile*
 
 ```ruby
-gem 'tramway-api'
+group :test do
+  gem 'rspec-rails', '~> 3.5'
+  gem 'rspec-json_expectations', '2.2.0'
+  gem 'factory_bot_rails', '~> 4.0'
+  gem 'json_matchers'
+  gem 'json_api_test_helpers', '1.1.1'
+end
 ```
 
-And then execute:
-```bash
-$ bundle
+Run `bundle install`
+
+Run `RAILS_ENV=test rails db:create db:migrate`
+
+Run `mkdir spec`
+
+Create file `spec/spec_helper.rb` with:
+
+```ruby
+ENV['RAILS_ENV'] ||= 'test'
+require File.expand_path('../config/environment', __dir__)
+require 'rspec/rails'
+require 'rspec/autorun'
+require 'rspec/expectations'
+require 'rspec/json_expectations'
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+end
 ```
 
-Or install it yourself as:
-```bash
-$ gem install tramway-api
+Create file `spec/rails_helper.rb` with:
+
+```ruby
+require 'spec_helper'
+require 'factory_bot'
+require 'rspec/rails'
+require 'rspec/json_expectations'
+require 'json_matchers/rspec'
+require 'json_api_test_helpers'
+require 'rake'
+
+RSpec.configure do |config|
+  config.include FactoryBot::Syntax::Methods
+  config.include RSpec::Rails::RequestExampleGroup, type: :feature
+  config.include JsonApiTestHelpers
+end
 ```
 
+# SignUp user
+
+Create file `spec/tramway_api_spec.rb` with:
+
+```ruby
+require 'rails_helper'
+
+RSpec.describe 'Post creating user', type: :feature do
+  describe 'POST /api/v1/user with model User' do
+    let(:attributes) { attributes_for :user }
+
+    it 'returns created status' do
+      post '/api/v1/user', params: { user: attributes }
+      expect(response.status).to eq 201
+    end
+    
+    it 'returns no errors' do
+      post '/api/v1/user', params: { user: attributes }
+
+      expect(json_response[:response]). to be_nil
+    end
+  end
+end
+```
+
+# SignIn User
+
+```ruby
+require 'rails_helper'
+
+RSpec.describe 'Post generate token', type: :feature do
+  describe 'POST /api/v1/user_token' do
+    let(:user) { create :user, password: '123456789' }
+
+    it 'returns created status' do
+      post '/api/v1/user_token', params: { auth: { login: user.email, password: '123456789' }  }
+
+      expect(response.status).to eq 201
+    end
+    
+    it 'returns token' do
+      post '/api/v1/user_token', params: { auth: { login: user.email, password: '123456789' }  }
+
+      expect(json_response[:auth_token].present?).to be_truthy
+      expect(json_response[:user]).to include_json({ email: user.email, uid: user.uid })
+    end
+
+  end
+end
+
+```
+
+Run `rspec` to test
+
+We have route `user`, which create new authenticable user.
+
+For other models we have route `records`.
+
+```
+~: rails routes
+     Prefix Verb URI Pattern Controller#Action
+tramway_api      /api        Tramway::Api::Engine
+
+Routes for Tramway::Api::Engine:
+ v1_user_token POST   /v1/user_token(.:format)       tramway/api/v1/user_tokens#create
+       v1_user GET    /v1/user(.:format)             tramway/api/v1/users#show
+               POST   /v1/user(.:format)             tramway/api/v1/users#create
+    v1_records GET    /v1/records(.:format)          tramway/api/v1/records#index
+               POST   /v1/records(.:format)          tramway/api/v1/records#create
+ new_v1_record GET    /v1/records/new(.:format)      tramway/api/v1/records#new
+edit_v1_record GET    /v1/records/:id/edit(.:format) tramway/api/v1/records#edit
+     v1_record GET    /v1/records/:id(.:format)      tramway/api/v1/records#show
+               PATCH  /v1/records/:id(.:format)      tramway/api/v1/records#update
+               PUT    /v1/records/:id(.:format)      tramway/api/v1/records#update
+               DELETE /v1/records/:id(.:format)      tramway/api/v1/records#destroy
+
+```
+
+## Methods
+
+### Initializer methods
+
+#### auth_config
+
+Sets default ActiveRecord model, which used as main user to be authenticated with JWT.
+
+`user_model` - model name
+`auth_attributes` - array of available attributes used as login. 
+
+this model must have field `password_digest`, because we use `bcrypt` gem for authentication (providing other name of password attribute instead of `password` is coming soon)
+
+### set_available_models
+
+Sets ActiveRecord models which will be used in API
+
+Argument is a hash. Keys are underscored models names, values are arrays of available methods for every model.
+
+Enabled methods:
+
+* create
+* update
+* show
+* index
+* destroy
+
+
 ## Contributing
 Contribution directions go here.
 

data/app/controllers/tramway/api/v1/records_controller.rb

@@ -2,6 +2,7 @@ module Tramway::Api::V1
   class RecordsController < ::Tramway::Api::V1::ApplicationController
     before_action :check_available_model_class
     before_action :check_available_model_action
+    before_action :authenticate_user_if_needed
 
     def index
       records = model_class.active.order(id: :desc).send params[:scope] || :all
@@ -22,7 +23,7 @@ module Tramway::Api::V1
     end
 
     def update
-      record_form = form_class.new model_class.find params[:id]
+      record_form = form_class.new model_class.active.find params[:id]
       if record_form.submit params[:data][:attributes]
         render json: record_form.model,
           serializer: serializer_class,
@@ -32,6 +33,21 @@ module Tramway::Api::V1
       end
     end
 
+    def show
+      record = model_class.active.find params[:id]
+      render json: record,
+        serializer: serializer_class,
+        status: :ok
+    end
+
+    def destroy
+      record = model_class.active.find params[:id]
+      record.remove
+      render json: record,
+        serializer: serializer_class,
+        status: :no_content
+    end
+
     private
 
     def check_available_model_class
@@ -39,7 +55,14 @@ module Tramway::Api::V1
     end
 
     def check_available_model_action
-      head :unprocessable_entity and return unless action_name.in? Tramway::Api.available_models[model_class.to_s].map(&:to_s)
+      actions = Tramway::Api.available_models[model_class.to_s][:open]&.map(&:to_s) || [] + Tramway::Api.available_models[model_class.to_s][:closed]&.map(&:to_s) || []
+      head :unprocessable_entity and return unless action_name.in? actions
+    end
+
+    def authenticate_user_if_needed
+      if action_name.in? Tramway::Api::available_models[model_class.to_s][:closed]&.map(&:to_s) || []
+        authenticate_user
+      end
     end
 
     def model_class

data/app/controllers/tramway/api/v1/users_controller.rb

@@ -6,6 +6,7 @@ class Tramway::Api::V1::UsersController < ::Tramway::Api::V1::ApplicationControl
 
   def create
     user_form = sign_up_form_class_name(Tramway::Api.user_based_model).new Tramway::Api.user_based_model.new
+    # Implement JSON API spec here
     if user_form.submit params[Tramway::Api.user_based_model.name.underscore]
       token = ::Knock::AuthToken.new(payload: { sub: user_form.model.id }).token
       # FIXME refactor this bullshit

data/lib/tramway/api/version.rb

@@ -1,5 +1,5 @@
 module Tramway
   module Api
-    VERSION = '1.1.0.1'
+    VERSION = '1.4'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tramway-api
 version: !ruby/object:Gem::Version
-  version: 1.1.0.1
+  version: '1.4'
 platform: ruby
 authors:
 - Pavel Kalashnikov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-08-05 00:00:00.000000000 Z
+date: 2019-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: knock
@@ -99,8 +99,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Engine for api