Deference hyperlink parameter before deriving the resource name

[syskill]

No description provided.

[geemus]

It's been a bit since I've worked with this (which makes it hard for me to recall some particulars). Could you provide a quick before/after example of what this would look like in practice? That way I can be more confident about the impact. Thanks!

[syskill]

pr-example.yaml.txt

Here is an example of a recurring pattern in my REST API. There are two resources, example frobs and example blobs. Frobs have one or more ancillary blobs. I have a CLI tool, generated automatically from the schema, with syntax like

$ exampletool example_frobs add_ancillary_blob example_frob=thisfrob ancillary_blob=3
$ exampletool example_frobs remove_ancillary_blob example_frob=thatfrob ancillary_blob=7

In order to generate sensible CLI syntax, I need the link parameter for ancillary blobs to end in /ancillary_blob; hence the definition #/definitions/example_frob/definitions/ancillary_blob.

Now, when I run prmd to generate an API doc, it cleverly dereferences #/definitions/example_frob/definitions/ancillary_blob to #/definitions/example_blob/definitions/id (there's an anyOf but it doesn't matter). Great! Except that prmd has already derived the resource name before dereferencing, so it names the link parameter example_frob_id. The example command is therefore rather misleading:

$ curl -n -X PUT http://example.org/example-frobs/$EXAMPLE_FROB_NAME_OR_ID/ancillary-blobs/$EXAMPLE_FROB_ID \
  -H "Content-Type: application/json"

After this commit, prmd gets it right:

$ curl -n -X PUT http://example.org/example-frobs/$EXAMPLE_FROB_NAME_OR_ID/ancillary-blobs/$EXAMPLE_BLOB_ID \
  -H "Content-Type: application/json"

[geemus]

I see, I don't think in my usage I've had nested definitions like that, which might be why I hadn't come across it. That all makes sense, thanks for taking the time to explain and share examples. LGTM.