Add support for deep-linking into specific APIs in Swagger/OpenAPI files
Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.
Proposal
I would like you to add support for the 'deepLinking' parameter that is part of the Swagger UI configuration. This allows links to a Swagger page to link to specific APIs, rather than to just the page as a whole. We need this feature to improve our system documentation, as we will be able to provide links from Confluence pages to specific APIs in our gitlab area.
Smartbear documentation on this config parameter can be found here: https://swagger.io/docs/open-source-tools/swagger-ui/usage/deep-linking/
An example of the difference in linking to a Swagger page and linking to a specific API:
Link #1 (closed) just takes the user to the Swagger page. If the page has "a lot" of APIs on it, it could be ambiguous as to why the user is being directed to the page. Link #2 (closed) expands the specific API and brings it to the top of the page. There is no ambiguity as to which API is being referenced. Through use of the 2nd type of link, we can discuss aspects of specific APIs in different areas (not Gitlab) and provide the user with a link to the full, authoritative details on the API.
Smartbear indicates that this ability is present but disabled by default. We need a way to enable it at some level. From most ideal to least ideal, we would be able to enable deep linking on:
- A file-by-file basis. (each Swagger file would support a flag to enable/disable this).
- A repo-by-repo basis. (each repo would support a flag to enable/disable this).
- Group-by-group, e.g. https://gitlab.com/top-level-namespace/sub-group
- Company-wide. (On or off for an entire namespace)
Alternatively, you could just enable the feature by default and then provide a mechanism to turn it off. I can't think of any down-side to enabling this feature - if users have access to the Swagger page, why not allow them to link to specific APIs?