{"id":18450875,"url":"https://github.com/patrixr/jsonapi-serializer-formats","last_synced_at":"2025-04-08T01:34:03.550Z","repository":{"id":56879505,"uuid":"340275671","full_name":"patrixr/jsonapi-serializer-formats","owner":"patrixr","description":":gem: Gem to enrich jsonapi-serializer with multiple formats","archived":false,"fork":false,"pushed_at":"2021-03-01T06:37:26.000Z","size":25,"stargazers_count":20,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-04-24T15:10:13.842Z","etag":null,"topics":["api-serializers","concern","gem","hacktoberfest","json","jsonapi","nested-formats","rails","ruby","ruby-gem","serializer"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/patrixr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-02-19T06:13:02.000Z","updated_at":"2022-02-14T12:56:54.000Z","dependencies_parsed_at":"2022-08-20T22:30:57.255Z","dependency_job_id":null,"html_url":"https://github.com/patrixr/jsonapi-serializer-formats","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrixr%2Fjsonapi-serializer-formats","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrixr%2Fjsonapi-serializer-formats/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrixr%2Fjsonapi-serializer-formats/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrixr%2Fjsonapi-serializer-formats/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/patrixr","download_url":"https://codeload.github.com/patrixr/jsonapi-serializer-formats/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247760853,"owners_count":20991531,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-serializers","concern","gem","hacktoberfest","json","jsonapi","nested-formats","rails","ruby","ruby-gem","serializer"],"created_at":"2024-11-06T07:26:47.906Z","updated_at":"2025-04-08T01:34:03.284Z","avatar_url":"https://github.com/patrixr.png","language":"Ruby","readme":"# JSON:API Serializer format module\n\nA module to enrich [JSON:API Serializers](https://github.com/jsonapi-serializer) with configurable formats.\n\n[![Version](https://img.shields.io/gem/v/jsonapi-serializer-formats)](https://rubygems.org/gems/jsonapi-serializer-formats)\n[![License](https://img.shields.io/github/license/rails/rails)](https://github.com/rails/rails)\n[![RSpec](https://github.com/patrixr/jsonapi-serializer-formats/actions/workflows/rspec.yml/badge.svg)](https://github.com/patrixr/jsonapi-serializer-formats/actions/workflows/rspec.yml)\n## Installation\n\nAdd this line to your Gemfile:\n\n```ruby\ngem 'jsonapi-serializer-formats'\n```\n\nExecute:\n\n```bash\n$ bundle install\n```\n\n## Serializer extension\n\nAfter the module is included in your existing serializer, the `format` keyword is now available for you to use\n\n\n```ruby\nclass MovieSerializer\n  include JSONAPI::Serializer\n  include JSONAPI::Formats\n\n  attributes :name\n\n  format :detailed do\n    attribute   :year\n    attribute   :rating\n\n    has_many :actors\n  end\nend\n```\n\n## Rendering\n\n### Default behaviour\n\nWhen no filter is specified, only the attributes declared at the root will be rendered.\n\n```ruby\nhash = MovieSerializer.new(movie).serializable_hash\n```\n\nOutput\n\n```json\n{\n  \"data\": {\n    \"id\": \"3\",\n    \"type\": \"movie\",\n    \"attributes\": {\n      \"name\": \"pulp fiction\"\n    }\n  }\n}\n```\n\n## Specifying a format\n\nWhen a format is specified during render, the attributes defined under that format will be included\n\n```ruby\nhash = MovieSerializer.new(movie, { params: { format: :detailed }}).serializable_hash\n```\n\nOutput\n\n```json\n{\n  \"data\": {\n    \"id\": \"3\",\n    \"type\": \"movie\",\n    \"attributes\": {\n      \"name\": \"pulp fiction\",\n      \"year\": \"1994\",\n      \"rating\": 5\n    },\n    \"relationships\": {\n      \"actors\": {\n        \"data\": [...]\n      }\n    }\n  }\n}\n```\n\n## Nested formats\n\nYou can nest formats one into another. A nested format will only render if **all** of its parent formats have been enabled during rendering\n\n```ruby\nclass MovieSerializer\n  include JSONAPI::Serializer\n  include JSONAPI::Formats\n\n  attributes :name\n\n  format :detailed do\n    attribute   :year\n\n    format :admin do\n      attribute :view_count\n    end\n  end\nend\n```\n\n```ruby\nhash = MovieSerializer.new(movie, { params: { format: [:detailed, :admin] } }).serializable_hash\n```\n\nRenders\n\n```json\n{\n  \"data\": {\n    \"id\": \"3\",\n    \"type\": \"movie\",\n    \"attributes\": {\n      \"name\": \"pulp fiction\",\n      \"year\": \"1994\",\n      \"view_count\": 98776\n    }\n  }\n}\n```\n\n## LICENSE\n\nMIT License\n\nCopyright (c) 2021 Patrick R\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrixr%2Fjsonapi-serializer-formats","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpatrixr%2Fjsonapi-serializer-formats","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrixr%2Fjsonapi-serializer-formats/lists"}