diff --git a/CHANGELOG.md b/CHANGELOG.md index 56bb058..c526017 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,10 @@ ## Changelog -### 1.5.0 (Next) +### 1.5.1 (Next) + +* ... + +### 1.5.0 (August 24, 2016) * [#61](https://github.com/ruby-grape/grape-active_model_serializers/pull/61): Adds support for collection serializers - [@drn](https://github.com/drn). * [#60](https://github.com/ruby-grape/grape-active_model_serializers/pull/60): Namespace serializer inference - [@drn](https://github.com/drn). diff --git a/UPGRADING.md b/UPGRADING.md index a007aa1..c1469c1 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -1,12 +1,145 @@ -### Upgrading to v.1.4.0 +### Upgrading to v1.5.0 + +#### ASM v0.10.x support added, v0.9.x support dropped + +[ASM](https://github.com/rails-api/active_model_serializers) introduced +breaking changes with ASM v0.10.x. Support has been introduced in v1.5.0. +If you require support for older version of ASM, please lock your Gemfile +to the relevant version. + +#### Non-collection Serializer Resolution + +Serializer resolution now uses the following strategy: + +1. Defined by the resource + +``` +class UsersApi < Grape::Api + resource :users do + get '/:id', serializer: SpecifiedUserSerializer do + current_user + end + end +end + +class User + def serializer_class + SpecifiedUserSerializer + end +end +``` + +2. Specified by options + +``` +class UsersApi < Grape::Api + resource :users do + get '/:id', serializer: SpecifiedUserSerializer do + current_user + end + end +end +``` + +2. Namespace inferred + +``` +class V1::UsersApi < Grape::Api + resource :users do + get '/:id' do + current_user + end + end +end +# 'V1::UsersApi'.deconstantize => 'V1' +# searches for serializers in the V1:: namespace with the name UserSerializer + +# used +class V1::UserSerializer + ... +end + +# not used since V1::UserSerializer resolved first +class UserSerializer + ... +end +``` + +3. Version inferred + +``` +class UsersApi < Grape::Api + version 'v2' + + resource :users do + get '/:id' do + current_user + end + end +end +# 'v2'.classify => V2 +# searches for serializers in the V2:: namespace with the name UserSerializer + +# used +class V2::UserSerializer + ... +end + +# not used since V2::UserSerializer resolved first +class UserSerializer + ... +end +``` + +4. Default ASM lookup + +``` +class V1::UsersApi < Grape::Api + version 'v2' + + resource :users do + get '/:id' do + current_user + end + end +end +# searches for serializers in the V1:: namespace, none found +# searches for serializers in the V2:: namespace, none found + +# used as no other serializers were found +class UserSerializer + ... +end +``` + +#### Collection Serializer Resolution + +Serializer resolution for collections also uses the above strategy, but has +the added option of overriding the member serializer if the `each_serializer` +options is specified. + +``` +class UsersApi < Grape::Api + resource :users do + get each_serializer: SpecifiedUserSerializer do + User.all + end + end +end +``` + + +### Upgrading to v1.4.0 #### Changes in Serializer Namespacing -Version 1.4.0 introduced changes in serializer namespacing when using Grape API versioning. +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. +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. @@ -48,7 +181,8 @@ module Chocolate end ``` -This will allow you to keep your serializers easier to maintain and more organized. +This will allow you to keep your serializers easier to maintain and more +organized. ``` app @@ -73,13 +207,15 @@ or alternatively: └── candy_bar_user_serializer.rb ``` -Thus, ActiveModelSerializer will fetch automatically the right serializer to render. +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. +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`. diff --git a/lib/grape-active_model_serializers/version.rb b/lib/grape-active_model_serializers/version.rb index 0497521..ec8136f 100644 --- a/lib/grape-active_model_serializers/version.rb +++ b/lib/grape-active_model_serializers/version.rb @@ -1,5 +1,5 @@ module Grape module ActiveModelSerializers - VERSION = '1.4.0'.freeze + VERSION = '1.5.0'.freeze end end