Doesn't handle links to parameter references

[beardedlinuxgeek]

When you have

"schema": {
    "$ref": "#/definitions/User"
}

then it will link to the User definition at the bottom. But if you have

"parameters": [{
    "$ref": "#/parameters/username"
}]

then the link is still created but because the parameter definitions are never added, there is nothing to link to. Also the description field doesn't get populated from the referenced parameter.

[jimmyjames]

Seeing this issue as well. Would be nice if the parameter description were inlined into the param description.

[auscaster]

Thanks guys, noted. If anyone has fixed this issue a PR would be very welcome. Its a simple fix, but will be away myself for the next couple of weeks so will be unable to take care of it straight away

[jimmyjames]

I may be able to submit a PR but am just getting up to speed with how spectacle works. Any nudges in the right direction is appreciated ;)

[auscaster]

OK that's great! Everything is based on handlebars so you could start with the `parameters.hbs` template and check into the helper JS that render `$ref` links.

…

On 26 January 2017 at 01:42, Jim Anderson ***@***.***> wrote: I may be able to submit a PR but am just getting up to speed with how spectacle works. Any nudges in the right direction is appreciated ;) — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#33 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAGKDAEHIbMMmr22JMxvDApMXiZykFj3ks5rV-wBgaJpZM4LkhdM> .

[jimmyjames]

I think the issue is that because it's a reference to a parameter type (we have common parameters for many apis), it ends up in the json-schema/reference template, which then just gets the url fixed up in helpers/schemaSubschemaName. That only accounts for #/definitions, which is fine for schema definitions. Parameters aren't rendered (and I think it would be odd to have parameters rendered themselves like schema definitions are) and the same code is used to handle definition links. What I would like is for the parameter reference to not be a link to its definition, but to be expanded inline. As a user it makes the most sense to view it that way, rather than have to navigate somewhere else and back.

I'll poke around some more to see how easy it would be to make that kind of change, but it seems spectacle makes an assumption that all $ref links should be links to their actual definition.

[auscaster]

Hi Jim, Thanks for looking into this! Since I don't use global parameter refs this way in my swagger files this way I haven't come across the issue yet. So you're using global parameters as per the example below, and want them to render as a normal parameter, correct? ``` "swagger": "2.0", "basePath": "/docs" "parameters": { "id": { "name": "id", "in": "path", "description": "Id of the item to get", "type": "number", "required": true, } } ``` This wont be too hard to do, the `root` data element which contains the full swagger doc is accessible from handlebars helpers so it should be pretty straight forward to resolve the reference by adding a new helper to handle parameter links. See how you go, and if you get stuck I can work through it with you when I'm back in the hot seat.

…

On 26 January 2017 at 19:49, Jim Anderson ***@***.***> wrote: I think the issue is that because it's a reference to a parameter type (we have common parameters for many apis), it ends up in the json-schema/reference template, which then just gets the url fixed up in helpers/schemaSubschemaName. That only accounts for #/definitions, which is fine for schema definitions. Parameters aren't rendered (and I think it would be odd to have parameters rendered themselves like schema definitions are) and the same code is used to handle definition links. What I would like is for the parameter reference to not be a link to its definition, but to be expanded inline. As a user it makes the most sense to view it that way, rather than have to navigate somewhere else and back. I'll poke around some more to see how easy it would be to make that kind of change, but it seems spectacle makes an assumption that all $ref links should be links to their actual definition. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#33 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAGKDIF3uL0rHMt8y_xcXOLsGUAkzexoks5rWOqcgaJpZM4LkhdM> .

[auscaster]

We have an ongoing PR over here for resolving remote references, there may be some crossover: #41

[CodeLenny]

@auscaster I'll probably be able to roll this into #41.

I'm guessing that I'll be using some config in the preprocessor to determine if references should be imported into each usage, or put in the global definitions and referenced from there. Then it's up to downstream elements to produce documentation for the parameters section, like it does for the definitions section.

[rjmanzer]

Did this ever get implemented? Links to parameters looks to still be broken.

[adamlc]

This is still broken for me too 😢

[auscaster]

This has not been implemented yet, sorry. I'm flat chat with other work right now but would be very open to a PR!

…

On 9 August 2017 at 14:50, Adam Curtis ***@***.***> wrote: This is still broken for me too 😢 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#33 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAGKDLiB9uZ1HAEK6xdkFyilPHIF8kv9ks5sWasEgaJpZM4LkhdM> .

[auscaster]

Fixed via PR, thanks so much :)