fix(API): move job update branch param from body to query #STRINGS-3488

[Efe Bikmaz (bikmazefe)]

What changed

paths/jobs/update.yaml documented branch as a settable property on the
Update Job request body, implying that PATCH-ing branch changes the
job's own branch. It doesn't -- strings-app's shared project-scoping
middleware (Api::ProjectLoading#load_project) consumes it purely to locate
a job that lives inside a branch, exactly like the sibling jobs/index.yaml
and jobs/show.yaml endpoints already document it (as the shared
parameters.yaml#/branch query parameter). job_params in the Rails
controller never permitted branch as a mutable field either, so the old
docs were actively misleading -- a schema-valid PATCH with branch in the
body would 404 if the job wasn't in that branch, looking like a
missing-resource error rather than a scoping mismatch.

• Removed branch from the Update Job request body schema.
• Added "$ref": "../../parameters.yaml#/branch" to the operation's
  parameters, matching jobs/index.yaml / jobs/show.yaml.
• Fixed the curl and CLI v2 code samples, which previously mixed branch
  into the mutable-fields JSON payload -- curl now uses ?branch=... in the
  query string, CLI now uses --branch <name> as its own flag.

No behavior change on the strings-app side; this only corrects the spec to
match what the API already does.

Related

• STRINGS-3488
• Companion strings-app PR (adds a request spec locking in the underlying
  behavior): https://github.com/Phrase-Engineering/strings-app/pull/18910

Testing

• npx swagger-cli validate main.yaml -- passes
• make lint (validate + bundle + generator validation) -- passes clean

🤖 Generated with Claude Code

[github-actions]

API changelog (oasdiff)

Doc-only edits (descriptions, examples) do not appear here.

2 changes: 0 error, 1 warning, 1 info
warning	[request-property-removed] at doc/compiled.json
	in API PATCH /projects/{project_id}/jobs/{id}
		removed the request property `branch`

info	[new-optional-request-parameter] at doc/compiled.json
	in API PATCH /projects/{project_id}/jobs/{id}
		added the new optional `query` request parameter `branch`