graphiti 2.0.0.beta.4 → 2.0.0.beta.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8f1b385d0a7623788b2a492d98d2175d1964d320ea48f988f73bffb30ab9439
-  data.tar.gz: a95f11de0a07753144d5c4d057ae0b4bb90e2f61c5906996bd29f7fa09998657
+  metadata.gz: e108e5f71103c3fb7f38f5328a890ff131b264201c583509081cfd3106a7b255
+  data.tar.gz: 18edd07b0ab429ec89309ec94164a2324a21bbbfbd6dd37f6e49bb6f9707f1c9
 SHA512:
-  metadata.gz: 7f00afaae7e44289e89d5d29e56e3539953e2c13befcc6c2d5dbb95c9b8904ca6103c3651ebabb6227f9e43f50f22ee4b845d1d9235244e363a1c08089363c47
-  data.tar.gz: a6f82ed9556a22d2ddd76710877af8f39cfca470cad5a12a05d99ef5d54fc6d03a5c0e549026307cd71b6a6323c51e4889164acd94a38a0d371e0c74fe54760a
+  metadata.gz: f2affdd800c2966ef15c5d1765b9d1acc48a032c3ee143b9283d69b9545290e227454d77559e25c94b4cd7b0131d0cdc2addbb031a4177155d8085086d818b3b
+  data.tar.gz: 79c294b775b8be269194cae7e61cf179a16ec8dd01e8b0b24e7a141d3333683bfbd54032e4c07623f6d2dc3fbe3ce6c721884658da89cbe24bfd9dac935f8e07

data/.github/workflows/ci.yml

@@ -41,25 +41,30 @@ jobs:
           - { ruby: "3.2", gemfile: Gemfile, appraisal: false }
           - { ruby: "3.3", gemfile: Gemfile, appraisal: false }
           - { ruby: "3.4", gemfile: Gemfile, appraisal: false }
+          - { ruby: "4.0", gemfile: Gemfile, appraisal: false }
           - { ruby: ruby-head, gemfile: Gemfile, appraisal: false }
 
           # Rails 7.1 - the floor
           - { ruby: "3.2", gemfile: gemfiles/rails_7_1.gemfile, appraisal: true }
           - { ruby: "3.4", gemfile: gemfiles/rails_7_1.gemfile, appraisal: true }
+          - { ruby: "4.0", gemfile: gemfiles/rails_7_1.gemfile, appraisal: true }
 
           # Rails 7.2
           - { ruby: "3.2", gemfile: gemfiles/rails_7_2.gemfile, appraisal: true }
           - { ruby: "3.4", gemfile: gemfiles/rails_7_2.gemfile, appraisal: true }
+          - { ruby: "4.0", gemfile: gemfiles/rails_7_2.gemfile, appraisal: true }
           - { ruby: ruby-head, gemfile: gemfiles/rails_7_2.gemfile, appraisal: true }
 
           # Rails 8.0
           - { ruby: "3.2", gemfile: gemfiles/rails_8_0.gemfile, appraisal: true }
           - { ruby: "3.4", gemfile: gemfiles/rails_8_0.gemfile, appraisal: true }
+          - { ruby: "4.0", gemfile: gemfiles/rails_8_0.gemfile, appraisal: true }
           - { ruby: ruby-head, gemfile: gemfiles/rails_8_0.gemfile, appraisal: true }
 
           # Rails 8.1
           - { ruby: "3.2", gemfile: gemfiles/rails_8_1.gemfile, appraisal: true }
           - { ruby: "3.4", gemfile: gemfiles/rails_8_1.gemfile, appraisal: true }
+          - { ruby: "4.0", gemfile: gemfiles/rails_8_1.gemfile, appraisal: true }
           - { ruby: ruby-head, gemfile: gemfiles/rails_8_1.gemfile, appraisal: true }
 
     continue-on-error: ${{ matrix.ruby == 'ruby-head' }}

data/.github/workflows/docs.yml

@@ -1,10 +1,9 @@
 name: Docs
 
-# Publishes the documentation site from beta so the deploy is exercised well
-# before it matters. Pages serves this repo under /graphiti/, and the root of
-# graphiti.dev comes from graphiti-api.github.io, so nothing here can affect
-# the live 1.x site. When the domain moves to this repo, drop DOCS_BASE_URL so
-# baseUrl returns to "/" and add website/static/CNAME.
+# Publishes the documentation site from beta. graphiti.dev now points at this
+# repo via website/static/CNAME, so this deploy is the live site: the 1.x
+# Jekyll site is frozen under website/static/1.13 and ships with every build,
+# and graphiti-api.github.io no longer serves the domain.
 on:
   push:
     branches: [beta]
@@ -39,8 +38,6 @@ jobs:
 
       - name: Build
         working-directory: website
-        env:
-          DOCS_BASE_URL: /graphiti/
         run: npm run build
 
       - name: Publish to gh-pages

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 graphiti changelog
 
+# [2.0.0-beta.6](https://github.com/graphiti-api/graphiti/compare/v2.0.0-beta.5...v2.0.0-beta.6) (2026-08-09)
+
+
+### Bug Fixes
+
+* reject invalid page parameters ([#537](https://github.com/graphiti-api/graphiti/issues/537)) ([bb3698b](https://github.com/graphiti-api/graphiti/commit/bb3698b52911c658c5d023ad8fd55b5106195001)), closes [#347](https://github.com/graphiti-api/graphiti/issues/347)
+* treat empty polymorphic configuration as unset ([#538](https://github.com/graphiti-api/graphiti/issues/538)) ([5c17899](https://github.com/graphiti-api/graphiti/commit/5c1789993fbb4638d4443cf014b8bef358addb80)), closes [#199](https://github.com/graphiti-api/graphiti/issues/199)
+
+
+### Features
+
+* Add graphiti:audit task to audit resources for issues ([84436ea](https://github.com/graphiti-api/graphiti/commit/84436eab7c7d0713ec6f355b62ba8b06913ee31a))
+* raise MissingRelationshipMethod when rendering reads an association the model does not define ([1c41cee](https://github.com/graphiti-api/graphiti/commit/1c41cee787b4f747d2906b2230f8fb926e3d887d))
+* rename always_include_resource_ids to resource_ids, with a belongs_to_resource_ids_by_default setting ([8b11151](https://github.com/graphiti-api/graphiti/commit/8b111516822f6fc6e3675b59941688791cb34e74))
+
+# [2.0.0-beta.5](https://github.com/graphiti-api/graphiti/compare/v2.0.0-beta.4...v2.0.0-beta.5) (2026-08-07)
+
+
+### Bug Fixes
+
+* drop the relationship guard install notice ([c204312](https://github.com/graphiti-api/graphiti/commit/c20431214e126cb8e72c82022ee4c852b10a024b))
+* keep rake task helpers out of the global namespace ([0a41a60](https://github.com/graphiti-api/graphiti/commit/0a41a6022fa4c9151948714c31db367aee330e22)), closes [graphiti-api/graphiti-rails#91](https://github.com/graphiti-api/graphiti-rails/issues/91)
+
+
+### Features
+
+* add rspec matchers for resource relationships and attributes ([70525f7](https://github.com/graphiti-api/graphiti/commit/70525f7e10c511aa0c867ecc873f63f1790b8247)), closes [graphiti-api/graphiti_spec_helpers#14](https://github.com/graphiti-api/graphiti_spec_helpers/issues/14)
+* let the resource generator name the controller ([6ea7141](https://github.com/graphiti-api/graphiti/commit/6ea714181f3da011cae9f42477b4c3681a7a90ff)), closes [graphiti-api/graphiti-rails#53](https://github.com/graphiti-api/graphiti-rails/issues/53)
+
 # [2.0.0-beta.4](https://github.com/graphiti-api/graphiti/compare/v2.0.0-beta.3...v2.0.0-beta.4) (2026-08-07)
 
 

data/docs/concepts/links.md

@@ -170,11 +170,11 @@ end
 
 ### Pagination Links {#pagination-links}
 
-Requesting big collections can result into slow responses sometimes. In order to avoid this, you could use [pagination](https://jsonapi.org/format/#fetching-pagination). It'll break your response into smaller pieces that will make your server responds faster. Paginations links can be present in your response in the following ways:
+Requesting large collections can make for slow responses. [Pagination](https://jsonapi.org/format/#fetching-pagination) breaks the response into smaller pieces, and pagination links tell the client how to walk them. They can appear in a response two ways.
 
 #### Showing by default {#pagination-links-showing-by-default}
 
-With this configuration, all the responses will return the pagination links
+Every collection response returns pagination links:
 
 ```ruby
 Graphiti.configure do |c|
@@ -184,7 +184,7 @@ end
 
 #### When requested {#pagination-links-when-requested}
 
-You can showing the pagination links when it was requested in the URL with `?pagination_links=true`
+Links are rendered only when the request asks for them with `?pagination_links=true`. Worth doing when the collection is large: the `last` link needs a total count, so rendering links costs a `stat(:total, :count)` on every request that gets them.
 
 ```ruby
 Graphiti.configure do |c|

data/docs/concepts/relationships.md

@@ -70,10 +70,20 @@ has_many :positions,
   writable: true,
   link: self.autolink, # default true
   single: false, # only allow this sideload when one employee
-  always_include_resource_ids: true # default: true for belongs_to, false otherwise
+  resource_ids: false
 ```
 
-`belongs_to` renders resource linkage by default, so a client can see which record a relationship points at without following the link:
+`resource_ids` is the one whose default depends on the relationship type:
+
+| type | renders resource ids by default |
+|---|---|
+| `belongs_to` | yes, when its foreign key already holds the related id |
+| `has_one` | no |
+| `has_many` | no |
+| `many_to_many` | no |
+| `polymorphic_belongs_to` | no |
+
+`belongs_to` renders them so a client can see which record a relationship points at without following the link:
 
 ```json
 "employee": {
@@ -82,19 +92,109 @@ has_many :positions,
 }
 ```
 
-That costs nothing, because the id is already on the parent as its foreign key. A `has_many` would have to run a query per record to answer the same question, so it stays off unless you ask for it.
+That costs nothing, because the id is already on the parent as its foreign key.
+
+No other relationship type has a free source for its ids. A collection accepts `resource_ids: true`, but that reads the association on every render of every parent record, whether or not the request wants the relationship. That is the N+1 from [#167](https://github.com/graphiti-api/graphiti/issues/167#issuecomment-686866646) on every response. Leave collections off and let clients `?include=` them.
 
-A `belongs_to` falls back to loading the association when the foreign key cannot answer for it: a `params` block or `base_scope` can filter out the record the key points at, a polymorphic target takes its type from the record rather than the relationship, and a remote resource has no local key to read. Turning linkage on for those, or for a `has_many`, brings back the 1+N described in [#167](https://github.com/graphiti-api/graphiti/issues/167#issuecomment-686866646).
+Not every `belongs_to` can use its foreign key. A `scope` or `params` block or a `base_scope` can filter out the record the key points at, a polymorphic target's type varies per record while rendered ids carry one type for the whole relationship, a remote resource has no local key to read, and a custom `primary_key` points the relationship at some other column. Those load the association instead, so they stay off by default too.
 
-Set the default for every relationship on a resource, whatever its type:
+<details>
+<summary>Which `belongs_to` declarations render resource ids, and which do not</summary>
+
+```ruby
+# yes. employee_id is the employee's id, so the payload already has it
+belongs_to :employee
+
+# no. nothing renders at all, ids included
+belongs_to :employee, readable: false
+
+# no. employee_id holds a name, not the related id
+belongs_to :employee, primary_key: :first_name
+
+# no. the base scope can exclude the employee the key points at, and
+# graphiti cannot know whether it does without running it
+belongs_to :employee, base_scope: -> { Employee.all }
+
+# no. a remote resource has no local foreign key to read
+belongs_to :employee, remote: "http://foo.com/employees"
+
+# no. the record's own class decides its type, so the key gives an id
+# with no type to pair it with
+belongs_to :employee, resource: CreditCardResource
+
+# no. the scope can exclude the employee the key points at, and graphiti
+# cannot know whether it does without running it
+belongs_to :employee do
+  scope { |ids| {type: :employees, conditions: {id: ids}} }
+end
+
+# no. same, a params filter can exclude the employee the key points at
+belongs_to :employee do
+  params { |hash, positions| hash[:filter][:active] = true }
+end
+
+# no. credit_card_type is local, but rendered ids carry one type for the
+# whole relationship and this one's varies per record
+polymorphic_belongs_to :credit_card do
+  group_by(:credit_card_type) do
+    on(:Visa).belongs_to :visa, resource: VisaResource
+  end
+end
+```
+
+Watch for the `scope`, `params` and `base_scope` cases. Nothing about those declarations looks like it concerns resource ids, so adding a scope block to filter a relationship also stops its ids from rendering.
+
+If you keep a `schema.json`, the schema check catches that. A relationship that renders resource ids is marked `linkage: true`, and one that stops rendering them is reported as a breaking change. Gaining them is additive and passes.
+
+To render ids anyway, opt in on the relationship and accept the query:
+
+```ruby
+belongs_to :employee, resource_ids: true do
+  scope { |ids| {type: :employees, conditions: {id: ids}} }
+end
+```
+
+Know what that buys for the `scope`, `params` and `base_scope` cases. Rendering reads the association off the model, which does not apply the block, so if the block narrows what sideloading returns, the ids will disagree with it. Opting in there says you know the two agree. A `primary_key`, polymorphic or remote relationship does resolve to the right id this way.
+
+</details>
+
+### belongs_to_resource_ids_by_default {#belongs-to-resource-ids}
+
+To change how far a `belongs_to` goes, across a whole API, set it on the resource everything inherits from:
 
 ```ruby
 class ApplicationResource < Graphiti::Resource
-  self.always_include_resource_ids_by_default = false
+  self.belongs_to_resource_ids_by_default = :foreign_key
 end
 ```
 
-Subclasses inherit it, and a relationship passing `always_include_resource_ids` explicitly still wins.
+| | |
+|---|---|
+| `:foreign_key` | Default. Render resource ids wherever the foreign key already holds the related id, and never run an extra query. |
+| `:always` | Render them for every `belongs_to`, loading the association when the foreign key cannot answer. A query per record, per relationship, on every render. |
+| `:never` | Render none. This is the 1.x payload. |
+
+Subclasses inherit it, and a relationship passing `resource_ids` explicitly still wins.
+
+All three describe requests that do not include the relationship. A relationship the request does include renders its ids whatever this is set to, `:never` included, because the records are already loaded and sitting in `included`.
+
+Before flipping the setting, [`bin/rake graphiti:audit`](/topics/debugging#graphiti-audit) reports how every relationship renders resource ids today and which would start loading the association.
+
+#### What a client sees {#relationship-payload-shapes}
+
+A client never has to work out which rule applied. The relationship object says what it knows:
+
+```json
+"employee": { "data": { "type": "employees", "id": "1" } }   // here is the id
+"employee": { "links": { "related": "..." } }                 // fetch it yourself
+"employee": { "meta": { "included": false } }                 // neither
+```
+
+The last shape appears only when a relationship has no ids **and** no link, which usually means `link: false`. It is not a general "was this sideloaded" flag. Relationships are autolinked by default, so the link shape is the one you normally see.
+
+The setting covers `belongs_to` and `polymorphic_belongs_to`, and no collection, deliberately. An API-wide `:always` on collections would be the N+1 from [#167](https://github.com/graphiti-api/graphiti/issues/167#issuecomment-686866646) applied everywhere at once.
+
+`:always` renders ids by loading the association, so a relationship naming a method the model does not have raises on every render once you set it.
 
 ### Conditional Relationships {#conditional-relationships}
 
@@ -221,7 +321,7 @@ Defaults to these common options:
 has_many :positions,
   foreign_key: :employee_id,
   primary_key: :id,
-  always_include_resource_ids: false,
+  resource_ids: false,
   resource: PositionResource
 ```
 
@@ -265,7 +365,7 @@ Defaults to these common options:
 belongs_to :employee,
   foreign_key: :employee_id,
   primary_key: :id,
-  always_include_resource_ids: false,
+  resource_ids: true,
   resource: EmployeeResource
 ```
 

data/docs/topics/debugging.md

@@ -172,6 +172,32 @@ Which add Debugger output as well.
 The `PATH` should not contain the domain unless you want to hit a live
 API instead of a test server.
 
+#### graphiti:audit {#graphiti-audit}
+
+> `bin/rake graphiti:audit`
+
+Audits every relationship declared across your resources. It reports anything that will raise at request time, relationships that load an association just to render resource ids, and `belongs_to` relationships that render no ids unless included. A checklist at the end shows what was checked:
+
+```
+ERROR will raise when the relationship is included: the model has no association method
+
+  EmployeeResource
+    has_many :positions  Employee has no #positions method
+
+  fix: define it, point the relationship at the real association with `as:`, or remove the relationship
+
+checks
+
+  ✓ all relationships inspectable
+  ✗ 1 association method missing
+  ✓ all readable guards defined
+  ✓ all sideload filters declared
+
+graphiti: 12 resources, 40 relationships, 1 error.
+```
+
+The task exits nonzero when there are errors, so it can hold the line in CI. Run it before and after flipping [belongs_to_resource_ids_by_default](/concepts/relationships#belongs-to-resource-ids) to see exactly what the setting changes.
+
 #### graphiti:benchmark {#graphiti-benchmark}
 
 > `bin/rake graphiti:benchmark[PATH,NUM_REQUESTS]`

data/docs/upgrading.md

@@ -13,9 +13,8 @@ Four things, and three of them fail loudly if you skip them.
 
 **1. Drop three gems.** `graphiti-rails`, `graphiti_spec_helpers` and `graphiti_errors` are now part of `graphiti` itself.
 
-```diff
-# Gemfile
-+ gem "graphiti"
+```diff title="Gemfile"
++ gem "graphiti", "~> 2.0.0.beta" # follows the betas and picks up 2.0 final when it ships
 - gem "graphiti-rails"
 - gem "graphiti_spec_helpers"
 - gem "graphiti_errors"
@@ -31,18 +30,14 @@ class ApplicationController < ActionController::Base
 end
 ```
 
-Skipping this fails at boot rather than at request time: a controller calling `sideload_allowlist` raises `NoMethodError` while its class body loads, so the app stops starting.
-
-If the controller already has `include Graphiti::Rails`, replace that line rather than adding to it. The old spelling still sets the controller up, so nothing breaks mid-upgrade, but it warns and goes away in the next major version.
+If the controller already has `include Graphiti::Rails`, replace it with `include Graphiti::Rails::Controller`. 
 
 <details>
 <summary>What the include actually brings, and what a controller without it loses</summary>
 
 Until 2.0, Graphiti added itself to **every** controller in the application: an `around_action` wrapping each request in a Graphiti context, another wrapping it in the debugger, and a catch-all exception handler, on Devise controllers, admin controllers, HTML pages, everything.
 
-`Graphiti::Rails::Controller` now bundles all of it, and where you include it decides the blast radius. `ApplicationController` matches 1.x behavior. An API base class scopes it and leaves the rest of the app alone.
-
-A controller without it gets no Graphiti context, no debugger, and none of Graphiti's exception handlers, so if a resource action sees an empty `Graphiti.context`, this include is what is missing.
+`Graphiti::Rails::Controller` now bundles all of it, and including it is required. Including it in `ApplicationController` matches 1.x behavior. Including it in an API base class scopes it and leaves the rest of the app alone. A controller without it gets no Graphiti context, no debugger, and none of Graphiti's exception handlers, so if a resource action sees an empty `Graphiti.context`, this include is what is missing.
 
 The class-level DSL travels with it, which is the one failure you see before a request is ever served:
 
@@ -133,9 +128,9 @@ It has to be a request spec. Exceptions are rendered in Rack middleware, which c
 Nothing to do here. These change what a client receives or when a callback runs, and none of them warns you, because none of them is a rename.
 
 <details>
-<summary>A `belongs_to` renders resource linkage in every payload, where 1.x sent only a link</summary>
+<summary>A `belongs_to` renders resource ids when its foreign key already holds them, where 1.x sent only a link</summary>
 
-A `belongs_to` now includes resource linkage in the payload by default, where 1.x sent only a link:
+A `belongs_to` now renders resource ids in the payload by default, where 1.x sent only a link:
 
 ```json
 "employee": { "data": { "type": "employees", "id": "1" }, "links": { "related": "..." } }
@@ -143,27 +138,29 @@ A `belongs_to` now includes resource linkage in the payload by default, where 1.
 
 The id comes from the foreign key already on the parent, so this costs no extra queries, and clients can resolve the relationship against data they already hold instead of following the link. `has_many` is unchanged, since answering there means a query per record.
 
-Not every `belongs_to` qualifies. A `scope` or `params` block, a `base_scope`, a polymorphic or remote target or a custom `primary_key` all mean the foreign key is not the related id, and those keep loading the association, so they stay opt-in as in 1.x.
+Not every `belongs_to` qualifies. A remote target or a custom `primary_key` mean the foreign key is not the related id, a polymorphic target means one rendered type cannot cover every record, and a `scope` or `params` block or a `base_scope` mean the key might not survive the filter. Rendering ids for those means loading the association, so they stay opt-in as in 1.x and render nothing until you ask.
 
-Relationships are marked `linkage: true` in `schema.json`, and the schema check reports a relationship that stops including it.
+Run [`bin/rake graphiti:audit`](/topics/debugging#graphiti-audit) to see where your API stands: it lists every relationship that renders no ids, and why.
 
 To go back to the old payload for one relationship:
 
 ```ruby
-belongs_to :employee, always_include_resource_ids: false
+belongs_to :employee, resource_ids: false
 ```
 
-Or for the whole API, on the resource everything inherits from. The same setting with `true` is the 2.0 replacement for the `Sideload::BelongsTo` monkey patch that [#167](https://github.com/graphiti-api/graphiti/issues/167) has been recommending, and it now covers every relationship type rather than only `belongs_to`:
+Or for the whole API, on the resource everything inherits from:
 
 ```ruby
 class ApplicationResource < Graphiti::Resource
   self.abstract_class = true
 
-  self.always_include_resource_ids_by_default = false
+  self.belongs_to_resource_ids_by_default = :never
 end
 ```
 
-How linkage is configured, and when a `belongs_to` cannot use its foreign key, is covered in [Customizing Relationships](/concepts/relationships#customizing-relationships).
+If you carry the `Sideload::BelongsTo` monkey patch from [#167](https://github.com/graphiti-api/graphiti/issues/167), delete it and set nothing. The default now covers the safe cases on its own. To force ids onto the rest the way the patch did, set `self.belongs_to_resource_ids_by_default = :always`, at a query per record for each one.
+
+The three settings, and when a `belongs_to` cannot use its foreign key, are covered in [Customizing Relationships](/concepts/relationships#belongs-to-resource-ids).
 
 </details>
 
@@ -229,6 +226,7 @@ Every name below still works, warns, and will be removed in the next major. They
 | `context_namespace` | `current_action` |
 | `Graphiti::Rails::DEPRECATOR` | `Graphiti::DEPRECATOR` (the old name still resolves) |
 | `require "graphiti_errors"`, `require "graphiti/responders"` | remove / no longer needed |
+| `always_include_resource_ids: true` on a relationship | `resource_ids: true` |
 
 `RSpec.describe PostResource, type: :resource` still picks up the resource-testing context automatically. That has not changed.
 
@@ -239,6 +237,9 @@ Every name below still works, warns, and will be removed in the next major. They
 | `include GraphitiErrors` | `register_exception` is available on every controller |
 | `GraphitiErrors::ExceptionHandler` | subclass `Graphiti::Rails::ExceptionHandler` |
 | `GraphitiErrors.enable!` / `.disable!` | `handle_request_exceptions` |
+| `self.always_include_resource_ids_by_default` | `self.belongs_to_resource_ids_by_default`, which takes `:foreign_key`, `:always` or `:never` |
+
+`always_include_resource_ids_by_default` only ever shipped in `2.0.0.beta.4`, so it is gone rather than deprecated and raises `NoMethodError` at class-definition time. It applied to every relationship type, and only a `belongs_to` can render resource ids without loading an association, so the replacement covers `belongs_to` alone. `= false` becomes `:never`. There is no equivalent of `= true`, because arming every collection API-wide is the behavior it was removed for. Use `:always` for `belongs_to`.
 
 ## Without Rails {#without-rails}
 

data/graphiti.gemspec

@@ -18,31 +18,13 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
   spec.required_ruby_version = ">= 3.2"
 
-  # TODO: remove once the 1.12 upgrade window has passed
-  spec.post_install_message = <<~MSG
-    Graphiti: relationship readable:/writable: guards are now enforced.
-
-    Symbols, strings, and procs passed to a relationship's readable/writable
-    guards were always interpreted as true and never actually called before this
-    conditional relationship change. They are now evaluated per-request, where
-    unreadable relationships are omitted from responses and includes, and unwritable
-    relationships reject writes.
-
-    To list every affected relationship in your app:
-
-      bin/rails runner 'puts Graphiti.guarded_relationships'
-
-    Audit these before deploying. Apps using schema.json will also see affected 
-    relationships flagged as "became guarded" by the schema check.
-  MSG
-
   spec.add_dependency "jsonapi-serializable", "~> 0.3.0"
   spec.add_dependency "jsonapi-renderer", "~> 0.2", ">= 0.2.2"
   spec.add_dependency "dry-types", ">= 0.15.0", "< 2.0"
   spec.add_dependency "rescue_registry", "~> 1.0"
   spec.add_dependency "concurrent-ruby", ">= 1.2", "< 2.0"
   spec.add_dependency "activesupport", ">= 7.1"
-  # Bundled (no longer default) as of Ruby 3.5; graphiti uses OpenStruct in lib/
+  # Bundled (no longer default) as of Ruby 4.0; graphiti uses OpenStruct in lib/
   spec.add_dependency "ostruct", ">= 0.5"
 
   spec.add_development_dependency "faraday", "~> 0.15"

data/lib/generators/graphiti/resource_generator.rb

@@ -32,6 +32,12 @@ module Graphiti
       aliases: ["--model", "-m"],
       desc: "Specify to use attributes from a particular model"
 
+    # No short alias: -c is already --omit-comments.
+    class_option :controller,
+      banner: "Name",
+      type: :string,
+      desc: "Generate the controller under this name instead of the resource's, e.g. Api::V1::Posts"
+
     desc "This generator creates a resource file at app/resources, as well as corresponding controller/specs/route/etc"
     def generate_all
       generate_model
@@ -125,8 +131,23 @@ module Graphiti
       defined?(::Responders)
     end
 
+    # Api::V1::Posts, Api::V1::PostsController and api/v1/posts all name the
+    # same controller. Normalizing here means the class name, the file path and
+    # the route all come from one place.
+    def controller_class_name
+      @controller_class_name ||= begin
+        given = options[:controller]
+        base = given ? given.sub(/Controller\z/, "").camelize : model_klass.name
+        "#{base.pluralize}Controller"
+      end
+    end
+
+    def controller_path
+      controller_class_name.sub(/Controller\z/, "").underscore
+    end
+
     def generate_controller
-      to = File.join("app/controllers", class_path, "#{file_name.pluralize}_controller.rb")
+      to = File.join("app/controllers", "#{controller_path}_controller.rb")
       template("controller.rb.erb", to)
     end
 
@@ -142,6 +163,9 @@ module Graphiti
 
     def generate_route
       code = "resources :#{file_name.pluralize}"
+      # Rails would otherwise infer the controller from the route name, which
+      # is only right when the controller was named after the resource.
+      code << %(, controller: "#{controller_path}") if options[:controller]
       code << %(, only: [#{actions.map { |a| ":#{a}" }.join(", ")}]) if actions.length < 5
       code << "\n"
       inject_into_file "config/routes.rb", after: /ApplicationResource.*$\n/ do

data/lib/generators/graphiti/templates/controller.rb.erb

@@ -1,5 +1,5 @@
 <% module_namespacing do -%>
-class <%= model_klass.name.pluralize %>Controller < ApplicationController
+class <%= controller_class_name %> < ApplicationController
   <%- if actions?('index') -%>
   def index
     <%= file_name.pluralize %> = <%= resource_klass %>.all(params)