sjs/grape-active_model_serializers
1
0
Fork 0
mirror of https://github.com/samsonjs/grape-active_model_serializers.git synced 2026-04-27 14:57:43 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge pull request #51 from dblock/changes

Browse source 
Added CHANGELOG, CONTRIBUTING, updated README and UPGRADING.
This commit is contained in:
Daniel Doubrovkine (dB.) @dblockdotorg 2016-05-17 12:15:01 -04:00
commit 300eed4128
4 changed files with 291 additions and 79 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

36
CHANGELOG.md Normal file
View file

@ -0,0 +1,36 @@
## Changelog
### 1.4.0 (Next)
* [#49](https://github.com/jrhe/grape-active_model_serializers/pull/49): Adds support for active model serializer namespace - [@syntaxTerr0r](https://github.com/syntaxTerr0r).
* [#36](https://github.com/jrhe/grape-active_model_serializers/pull/36), [#50](https://github.com/jrhe/grape-active_model_serializers/pull/50): Added support through Grape 0.16.x - [@dblock](https://github.com/dblock).
### v1.3.2 (February 27, 2015)
* [#39](https://github.com/jrhe/grape-active_model_serializers/pull/39): Look for namespace and other options to configure serializers - [@jwkoelewijn](https://github.com/jwkoelewijn).
* [#40](https://github.com/jrhe/grape-active_model_serializers/pull/40): Use env to pass AMS meta around - [@dblock](https://github.com/dblock).
### v1.3.1 (November 20, 2014)
* [#30](https://github.com/jrhe/grape-active_model_serializers/pull/30): Read options from default_serializer_options - [@siong1987](https://github.com/siong1987).
* [#24](https://github.com/jrhe/grape-active_model_serializers/pull/24): Makes it possible to use `current_user` within serializers - [@sonxurxo](https://github.com/sonxurxo).
### v1.2.1 (July 23, 2014)
* [#21](https://github.com/jrhe/grape-active_model_serializers/pull/21): Correctly fetch serialization scope - [@radanskoric](https://github.com/radanskoric).
* [#18](https://github.com/jrhe/grape-active_model_serializers/pull/18): Added support for active model serializer 0.9.x - [@sbounmy](https://github.com/sbounmy).
* [#15](https://github.com/jrhe/grape-active_model_serializers/pull/15): Added `render` syntactic sugar - [@zph](https://github.com/zph).
* [#14](https://github.com/jrhe/grape-active_model_serializers/pull/14): Fix: `default_root` method to support symbol route in Grape - [@wjp2013](https://github.com/wjp2013).
* [#12](https://github.com/jrhe/grape-active_model_serializers/pull/12): Added support for `current_user` - [@kpassapk](https://github.com/kpassapk).
* [#11](https://github.com/jrhe/grape-active_model_serializers/pull/11): Fixed require path - [@schickling](https://github.com/schickling).
### v1.0.1 (September 9, 2013)
* [#6](https://github.com/jrhe/grape-active_model_serializers/pull/6): Conform to ActiveModel::Serializers way of determining array-ness - [@tfe](https://github.com/tfe).
* [#4](https://github.com/jrhe/grape-active_model_serializers/pull/4): Support for namespace options and rely more on active_model_serializers - [@johnallen3d](https://github.com/johnallen3d).
* [#1](https://github.com/jrhe/grape-active_model_serializers/pull/1): Fix: Grape::ActiveModelSerializers for models with compound names - [@george](https://github.com/george).
### v1.0.0
* Initial public release - [@jrhe](https://github.com/jrhe).

126
CONTRIBUTING.md Normal file
View file

@ -0,0 +1,126 @@
# Contributing to Grape-Swagger
This project is work of [many contributors](https://github.com/jrhe/grape-active_model_serializers/graphs/contributors).
You're encouraged to submit [pull requests](https://github.com/jrhe/grape-active_model_serializers/pulls),
[propose features and discuss issues](https://github.com/jrhe/grape-active_model_serializers/issues).
When in doubt, ask a question in the [Grape Google Group](http://groups.google.com/group/ruby-grape).
In the examples below, substitute your Github username for `contributor` in URLs.
## Fork the Project
Fork the [project on Github](https://github.com/jrhe/grape-active_model_serializers) and check out your copy.
```
git clone https://github.com/contributor/grape-active_model_serializers.git
cd grape-active_model_serializers
git remote add upstream https://github.com/jrhe/grape-active_model_serializers.git
```
## Create a Topic Branch
Make sure your fork is up-to-date and create a topic branch for your feature or bug fix.
```
git checkout master
git pull upstream master
git checkout -b my-feature-branch
```
## Bundle Install and Test
Ensure that you can build the project and run tests.
```
bundle install
bundle exec rake
```
## Write Tests
Try to write a test that reproduces the problem you're trying to fix or describes a feature that you want to build.
Add to [spec](spec).
We definitely appreciate pull requests that highlight or reproduce a problem, even without a fix.
## Write Code
Implement your feature or bug fix.
Ruby style is enforced with [RuboCop](https://github.com/bbatsov/rubocop).
Run `bundle exec rubocop` and fix any style issues highlighted.
Make sure that `bundle exec rake` completes without errors.
## Write Documentation
Document any external behavior in the [README](README.md).
## Update Changelog
Add a line to [CHANGELOG](CHANGELOG.md) under *Next Release*.
Make it look like every other line, including your name and link to your Github account.
## Commit Changes
Make sure git knows your name and email address:
```
git config --global user.name "Your Name"
git config --global user.email "contributor@example.com"
```
Writing good commit logs is important. A commit log should describe what changed and why.
```
git add ...
git commit
```
## Push
```
git push origin my-feature-branch
```
## Make a Pull Request
Go to https://github.com/contributor/grape-active_model_serializers and select your feature branch.
Click the 'Pull Request' button and fill out the form. Pull requests are usually reviewed within a few days.
## Rebase
If you've been working on a change for a while, rebase with upstream/master.
```
git fetch upstream
git rebase upstream/master
git push origin my-feature-branch -f
```
## Update CHANGELOG Again
Update the [CHANGELOG](CHANGELOG.md) with the pull request number. A typical entry looks as follows.
```
* [#123](https://github.com/jrhe/grape-active_model_serializers/pull/123): Reticulated splines - [@contributor](https://github.com/contributor).
```
Amend your previous commit and force push the changes.
```
git commit --amend
git push origin my-feature-branch -f
```
## Check on Your Pull Request
Go back to your pull request after a few minutes and see whether it passed muster with Travis-CI. Everything should look green, otherwise fix issues and amend your commit as described above.
## Be Patient
It's likely that your change will not be merged and that the nitpicky maintainers will ask you to do more, or fix seemingly benign problems. Hang on there!
## Thank You
Please do know that we really appreciate and value your time and work. We love you, really.

104
README.md
View file

@ -2,26 +2,17 @@
Use [active_model_serializers](https://github.com/rails-api/active_model_serializers) with [Grape](https://github.com/intridea/grape)! Use [active_model_serializers](https://github.com/rails-api/active_model_serializers) with [Grape](https://github.com/intridea/grape)!
[![Build Status](https://api.travis-ci.org/jrhe/grape-active_model_serializers.png)](http://travis-ci.org/jrhe/grape-active_model_serializers) [![Dependency Status](https://gemnasium.com/jrhe/grape-active_model_serializers.png)](https://gemnasium.com/jrhe/grape-active_model_serializers) [![Code Climate](https://codeclimate.com/github/jrhe/grape-active_model_serializers.png)](https://codeclimate.com/github/jrhe/grape-active_model_serializers) [![Build Status](https://api.travis-ci.org/jrhe/grape-active_model_serializers.svg)](http://travis-ci.org/jrhe/grape-active_model_serializers) [![Dependency Status](https://gemnasium.com/jrhe/grape-active_model_serializers.svg)](https://gemnasium.com/jrhe/grape-active_model_serializers) [![Code Climate](https://codeclimate.com/github/jrhe/grape-active_model_serializers.svg)](https://codeclimate.com/github/jrhe/grape-active_model_serializers)
## Breaking Changes
#### v1.4.0
* *BREAKING* Changes behaviour in serializer namespacing when using Grape API versioning. See [API versioning](https://github.com/jrhe/grape-active_model_serializers#api-versioning)
#### v1.0.0
* *BREAKING* Changes behaviour of root keys when serialising arrays. See [Array roots](https://github.com/jrhe/grape-active_model_serializers#array-roots)
## Installation ## Installation
Add the `grape` and `grape-active_model_serializers` gems to Gemfile. Add the `grape` and `grape-active_model_serializers` gems to Gemfile and run `bundle install`.
```ruby ```ruby
gem 'grape'
gem 'grape-active_model_serializers' gem 'grape-active_model_serializers'
``` ```
And then execute: See [UPGRADING](UPGRADING.md) if you're upgrading from a previous version.
bundle
## Usage ## Usage
@ -32,7 +23,6 @@ And then execute:
require 'grape-active_model_serializers' require 'grape-active_model_serializers'
``` ```
### Tell your API to use Grape::Formatter::ActiveModelSerializers ### Tell your API to use Grape::Formatter::ActiveModelSerializers
```ruby ```ruby
@ -42,8 +32,7 @@ class API < Grape::API
end end
``` ```
### Writing Serializers
### Writing serializers
See [active_model_serializers](https://github.com/rails-api/active_model_serializers) See [active_model_serializers](https://github.com/rails-api/active_model_serializers)
@ -61,8 +50,11 @@ end
``` ```
In this case, as User objects are being returned, grape-active_model_serializers will look for a serializer named UserSerializer. In this case, as User objects are being returned, grape-active_model_serializers will look for a serializer named UserSerializer.
### Array roots ### Array Roots
When serializing an array, the array root is set to the innermost namespace name if there is one, otherwise it is set to the route name (e.g. get 'name').
When serializing an array, the array root is set to the innermost namespace name if there is one, otherwise it is set to the route name.
In the following API the array root is `users`.
```ruby ```ruby
namespace :users do namespace :users do
@ -70,38 +62,32 @@ namespace :users do
@user = User.find(params[:id]) @user = User.find(params[:id])
end end
end end
# root = users
``` ```
In the following example the array root is `people`.
```ruby ```ruby
get "people" do get "people" do
@user = User.all @user = User.all
end end
# root = people
``` ```
### API versioning ### API Versioning
If you haven't declared an API version in Grape, nothing change. If your Grape API is versioned you must namespace your serializers accordingly.
If your Grape API is versioned, which means you have declared at least one version in Grape, ie: For example, given the following API.
```ruby ```ruby
module CandyBar module CandyBar
class Core < Grape::API class Core < Grape::API
version 'candy_bar', using: :header, vendor: 'acme' version 'candy_bar', using: :header, vendor: 'acme'
# My shiny endpoints
# ...
end end
end end
module Chocolate module Chocolate
class Core < Grape::API class Core < Grape::API
version 'chocolate', using: :header, vendor: 'acme' version 'chocolate', using: :header, vendor: 'acme'
# My shiny endpoints
# ...
end end
end end
@ -114,7 +100,7 @@ class API < Grape::API
end end
``` ```
You'll have to namespace your serializers according to each version, ie: Namespace your serializers according to each version.
```ruby ```ruby
module CandyBar module CandyBar
@ -130,7 +116,7 @@ module Chocolate
end end
``` ```
Which allow you to keep your serializers easier to maintain and more organized. This keeps serializers organized.
``` ```
app app
@ -147,7 +133,7 @@ app
└── user_serializer.rb └── user_serializer.rb
``` ```
or alternatively: Or as follows.
``` ```
└── serializers └── serializers
@ -155,7 +141,7 @@ or alternatively:
└── candy_bar_user_serializer.rb └── candy_bar_user_serializer.rb
``` ```
Thus, ActiveModelSerializer will fetch automatically the right serializer to render. ActiveModelSerializer will fetch automatically the right serializer to render.
### Manually specifying serializer options ### Manually specifying serializer options
@ -178,7 +164,7 @@ namespace 'foo', serializer: BarSerializer do
end end
``` ```
### Custom metadata along with the resources ### Custom Metadata
```ruby ```ruby
# Control any additional metadata using meta and meta_key # Control any additional metadata using meta and meta_key
@ -188,23 +174,21 @@ get "/homes"
end end
``` ```
### Support for `default_serializer_options` ### Default Serializer Options
```ruby ```ruby
helpers do helpers do
def default_serializer_options def default_serializer_options
{only: params[:only], except: params[:except]} { only: params[:only], except: params[:except] }
end end
end end
``` ```
### current_user ### Current User
One of the nice features of ActiveModel::Serializers is that it One of the nice features of ActiveModel::Serializers is that it provides access to the authorization context via the `current_user`.
provides access to the authorization context via the `current_user`.
In Grape, you can get the same behavior by defining a `current_user` In Grape, you can get the same behavior by defining a `current_user` helper method.
helper method:
```ruby ```ruby
helpers do helpers do
@ -218,12 +202,10 @@ helpers do
end end
``` ```
Then, in your serializer, you could show or hide some elements Then, in your serializer, you could show or hide some elements based on the current user's permissions.
based on the current user's permissions:
```ruby ```ruby
class PostSerializer < ActiveModel::Serializer class PostSerializer < ActiveModel::Serializer
...
def include_admin_comments? def include_admin_comments?
current_user.roles.member? :admin current_user.roles.member? :admin
end end
@ -252,42 +234,10 @@ end
API.new.get "/home" # => '{ user: { first_name: "JR", last_name: "HE" } }' API.new.get "/home" # => '{ user: { first_name: "JR", last_name: "HE" } }'
``` ```
## RSpec
See "Writing Tests" in https://github.com/intridea/grape.
Enjoy :)
## Changelog
#### Next
* Adds support for Grape 0.10.x
#### v1.4.0
* Adds support for active model serializer namespace
#### v1.2.1
* Adds support for active model serializer 0.9.x
#### v1.0.0
* Released on rubygems.org
* *BREAKING* Changes behaviour of root keys when serialising arrays. See [Array roots](https://github.com/jrhe/grape-active_model_serializers#array-roots)
## Contributing ## Contributing
1. Fork it See [CONTRIBUTING](CONTRIBUTING.md).
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Added some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request
## History
## Thanks to
The developers and maintainers of:
[active_model_serializers](https://github.com/rails-api/active_model_serializers)
[Grape](https://github.com/intridea/grape)!
Structured and based upon [grape-rabl](https://github.com/LTe/grape-rabl). Structured and based upon [grape-rabl](https://github.com/LTe/grape-rabl).

100
UPGRADING.md Normal file
View file

@ -0,0 +1,100 @@
### Upgrading to v.1.4.0
#### Changes in Serializer Namespacing
Version 1.4.0 introduced changes in serializer namespacing when using Grape API versioning.
If you haven't declared an API version in Grape, nothing changed.
If your Grape API is versioned, which means you have declared at least one version in Grape, you must namespace your serializers accordingly.
For example, given the following API.
```ruby
module CandyBar
class Core < Grape::API
version 'candy_bar', using: :header, vendor: 'acme'
end
end
module Chocolate
class Core < Grape::API
version 'chocolate', using: :header, vendor: 'acme'
end
end
class API < Grape::API
format :json
formatter :json, Grape::Formatter::ActiveModelSerializers
mount CandyBar::Core
mount Chocolate::Core
end
```
Namespace serializers according to each version.
```ruby
module CandyBar
class UserSerializer < ActiveModel::Serializer
attributes :first_name, :last_name, :email
end
end
module Chocolate
class UserSerializer < ActiveModel::Serializer
attributes :first_name, :last_name
end
end
```
This will allow you to keep your serializers easier to maintain and more organized.
```
app
└── api
├── chocolate
└── core.rb
└── candy_bar
└── core.rb
api.rb
└── serializers
├── chocolate
└── user_serializer.rb
└── candy_bar
└── user_serializer.rb
```
or alternatively:
```
└── serializers
├── chocolate_user_serializer.rb
└── candy_bar_user_serializer.rb
```
Thus, ActiveModelSerializer will fetch automatically the right serializer to render.
### Upgrading to v1.0.0
#### Changes to Array Roots
When serializing an array, the array root is set to the innermost namespace name if there is one, otherwise it is set to the route name.
In the following example the array root is `users`.
```ruby
namespace :users do
get ":id" do
@user = User.find(params[:id])
end
end
```
In the following example the array root is `people`.
```ruby
get "people" do
@user = User.all
end
```