From af83c9731d8a165505ab70ac0a17863b35972b1a Mon Sep 17 00:00:00 2001 From: Redeem-Grimm-Satoshi Date: Sun, 9 Aug 2026 00:51:47 -0400 Subject: [PATCH] fix(swagger): correct /shapes filter[route] parameter description The `filter[route]` parameter on `/shapes` was documented via the shared `filter_param(:id, name: :route)` helper, which renders the description "Filter by `/data/{index}/relationships/route/data/id`". That JSON pointer cannot be resolved against a `/shapes` response on any currently supported API version. `ApiWeb.ShapeView.relationships/2` returns an empty map for versions >= 2020-05-01, so shape resources carry no `relationships` member at all. The pointer is accurate for 2019-07-01 and earlier, where the view still emits `route` and `stops`, but it has been stale for the default version since 2020-05-01. Because `/shapes` also accepts `include` without validating it and returns 200, a client that follows the documented pointer and requests `include=route` receives a success response with no linkage data and no diagnostic, which makes the mismatch difficult to diagnose from the outside. This replaces the generated pointer text with an accurate description of what the filter accepts, keeps the existing comma-separated-list convention and `required: true`, and notes the 2020-05-01 boundary so callers needing route attribution know to request a single route at a time. No behavior change; documentation only. --- .../lib/api_web/controllers/shape_controller.ex | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/apps/api_web/lib/api_web/controllers/shape_controller.ex b/apps/api_web/lib/api_web/controllers/shape_controller.ex index e08ab44de..2463f5eda 100644 --- a/apps/api_web/lib/api_web/controllers/shape_controller.ex +++ b/apps/api_web/lib/api_web/controllers/shape_controller.ex @@ -22,7 +22,21 @@ defmodule ApiWeb.ShapeController do """) common_index_parameters(__MODULE__, :shape) - filter_param(:id, name: :route, required: true) + + parameter( + "filter[route]", + :query, + :string, + """ + Filter by route ID. Multiple route IDs #{comma_separated_list()}. + + Note that the shape resource does not include a `route` relationship on API versions \ + `2020-05-01` and later, so shapes in the response cannot be attributed to a route from \ + the response body on those versions. Request a single route at a time if that \ + attribution is needed. + """, + required: true + ) consumes("application/vnd.api+json") produces("application/vnd.api+json")