Should param in path also appear in body?

[TySpring]

If I have an endpoint with a named parameter in the path, like PATCH 'jobs/:job_id', and definitions like this:

params do
  requires(
    :job_notices,
    type: Array[String],
    documentation: {
      param_type: 'body',
      type: 'String',
      is_array: true,
      desc: 'job notices',
    },
  )
  requires(
    :job_id,
    type: String,
    desc: "ID of the job",
  )
end

patch 'jobs/:job_id' do
  # ...
end

I get the job_id param in the PATCH request body, as well as a separate entry for it in the path (job_id appears in 2 different places). This seems redundant, is this intentional behavior, or can/should the job_id key in the JSON request body be removed?

Example screenshot from swagger-UI:

This also generates a strange example CURL request in the documentation. The output:

curl -X PATCH --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
  "job_notices": ["done"],
  "job_id": "J456"
}' 'http://localhost:3000/api/jobs/J123'

^This suggests that you can pass the "job_id" in the request body (here as "J456"), but in reality this will be ignored in favor of the job_id in the path (here as "J123"). This may confuse clients of the API reading the docs.

[dblock]

This is interesting. Route params are automatically required to match the route, however you can document them the way you did. I think this is a bug or a non-feature, aka there should be a way to supply documentation for route parameters without making them actual additional query string parameters, with documentation.

[aschuster3]

@TySpring Did you check to make sure that job_id is not a readOnly parameter? There are a few ways to do that, one of which is manually inspecting your JSON output under the patchApiJobsJobId definition and looking for "readOnly": true.

[TySpring]

@aschuster3 actually job_id was a readOnly parameter. However, I was trying to reproduce to answer you, and saw that you have actually addressed my issue in This PR, specifically in 1657881. So, I am satisfied because it seems like the redundancy in documentation was removed. Thanks!