mirror of
https://github.com/samsonjs/grape-active_model_serializers.git
synced 2026-03-25 08:45:55 +00:00
Added CHANGELOG, CONTRIBUTING, updated README and UPGRADING. [ci skip]
This commit is contained in:
dblock
parent
4190cbf18f
commit
9a56be4d46
4 changed files with 291 additions and 79 deletions
36
CHANGELOG.md
Normal file
36
CHANGELOG.md
Normal 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
126
CONTRIBUTING.md
Normal 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.
|
||||
108
README.md
108
README.md
|
|
@ -2,26 +2,17 @@
|
|||
|
||||
Use [active_model_serializers](https://github.com/rails-api/active_model_serializers) with [Grape](https://github.com/intridea/grape)!
|
||||
|
||||
[](http://travis-ci.org/jrhe/grape-active_model_serializers) [](https://gemnasium.com/jrhe/grape-active_model_serializers) [](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)
|
||||
[](http://travis-ci.org/jrhe/grape-active_model_serializers) [](https://gemnasium.com/jrhe/grape-active_model_serializers) [](https://codeclimate.com/github/jrhe/grape-active_model_serializers)
|
||||
|
||||
## 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
|
||||
gem 'grape'
|
||||
gem 'grape-active_model_serializers'
|
||||
```
|
||||
|
||||
And then execute:
|
||||
|
||||
bundle
|
||||
See [UPGRADING](UPGRADING.md) if you're upgrading from a previous version.
|
||||
|
||||
## Usage
|
||||
|
||||
|
|
@ -32,7 +23,6 @@ And then execute:
|
|||
require 'grape-active_model_serializers'
|
||||
```
|
||||
|
||||
|
||||
### Tell your API to use Grape::Formatter::ActiveModelSerializers
|
||||
|
||||
```ruby
|
||||
|
|
@ -42,8 +32,7 @@ class API < Grape::API
|
|||
end
|
||||
```
|
||||
|
||||
|
||||
### Writing serializers
|
||||
### Writing 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.
|
||||
|
||||
### 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').
|
||||
### 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 API the array root is `users`.
|
||||
|
||||
```ruby
|
||||
namespace :users do
|
||||
|
|
@ -70,51 +62,45 @@ namespace :users do
|
|||
@user = User.find(params[:id])
|
||||
end
|
||||
end
|
||||
# root = users
|
||||
```
|
||||
|
||||
In the following example the array root is `people`.
|
||||
|
||||
```ruby
|
||||
get "people" do
|
||||
@user = User.all
|
||||
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
|
||||
module CandyBar
|
||||
class Core < Grape::API
|
||||
version 'candy_bar', using: :header, vendor: 'acme'
|
||||
|
||||
# My shiny endpoints
|
||||
# ...
|
||||
end
|
||||
end
|
||||
|
||||
module Chocolate
|
||||
class Core < Grape::API
|
||||
version 'chocolate', using: :header, vendor: 'acme'
|
||||
|
||||
# My shiny endpoints
|
||||
# ...
|
||||
end
|
||||
end
|
||||
|
||||
class API < Grape::API
|
||||
class API < Grape::API
|
||||
format :json
|
||||
formatter :json, Grape::Formatter::ActiveModelSerializers
|
||||
|
||||
mount CandyBar::Core
|
||||
mount Chocolate::Core
|
||||
mount Chocolate::Core
|
||||
end
|
||||
```
|
||||
|
||||
You'll have to namespace your serializers according to each version, ie:
|
||||
Namespace your serializers according to each version.
|
||||
|
||||
```ruby
|
||||
module CandyBar
|
||||
|
|
@ -130,7 +116,7 @@ module Chocolate
|
|||
end
|
||||
```
|
||||
|
||||
Which allow you to keep your serializers easier to maintain and more organized.
|
||||
This keeps serializers organized.
|
||||
|
||||
```
|
||||
app
|
||||
|
|
@ -147,7 +133,7 @@ app
|
|||
└── user_serializer.rb
|
||||
```
|
||||
|
||||
or alternatively:
|
||||
Or as follows.
|
||||
|
||||
```
|
||||
└── serializers
|
||||
|
|
@ -155,7 +141,7 @@ or alternatively:
|
|||
└── 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
|
||||
|
||||
|
|
@ -178,7 +164,7 @@ namespace 'foo', serializer: BarSerializer do
|
|||
end
|
||||
```
|
||||
|
||||
### Custom metadata along with the resources
|
||||
### Custom Metadata
|
||||
|
||||
```ruby
|
||||
# Control any additional metadata using meta and meta_key
|
||||
|
|
@ -188,23 +174,21 @@ get "/homes"
|
|||
end
|
||||
```
|
||||
|
||||
### Support for `default_serializer_options`
|
||||
### Default Serializer Options
|
||||
|
||||
```ruby
|
||||
helpers do
|
||||
def default_serializer_options
|
||||
{only: params[:only], except: params[:except]}
|
||||
{ only: params[:only], except: params[:except] }
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
### current_user
|
||||
### Current User
|
||||
|
||||
One of the nice features of ActiveModel::Serializers is that it
|
||||
provides access to the authorization context via the `current_user`.
|
||||
One of the nice features of ActiveModel::Serializers is that it provides access to the authorization context via the `current_user`.
|
||||
|
||||
In Grape, you can get the same behavior by defining a `current_user`
|
||||
helper method:
|
||||
In Grape, you can get the same behavior by defining a `current_user` helper method.
|
||||
|
||||
```ruby
|
||||
helpers do
|
||||
|
|
@ -218,12 +202,10 @@ helpers do
|
|||
end
|
||||
```
|
||||
|
||||
Then, in your serializer, you could show or hide some elements
|
||||
based on the current user's permissions:
|
||||
Then, in your serializer, you could show or hide some elements based on the current user's permissions.
|
||||
|
||||
```ruby
|
||||
class PostSerializer < ActiveModel::Serializer
|
||||
...
|
||||
def include_admin_comments?
|
||||
current_user.roles.member? :admin
|
||||
end
|
||||
|
|
@ -252,42 +234,10 @@ end
|
|||
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
|
||||
|
||||
1. Fork it
|
||||
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
|
||||
See [CONTRIBUTING](CONTRIBUTING.md).
|
||||
|
||||
|
||||
## Thanks to
|
||||
The developers and maintainers of:
|
||||
[active_model_serializers](https://github.com/rails-api/active_model_serializers)
|
||||
[Grape](https://github.com/intridea/grape)!
|
||||
## History
|
||||
|
||||
Structured and based upon [grape-rabl](https://github.com/LTe/grape-rabl).
|
||||
|
|
|
|||
100
UPGRADING.md
Normal file
100
UPGRADING.md
Normal 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
|
||||
```
|
||||
Loading…
Reference in a new issue