swagger-ui
swagger-ui copied to clipboard
swagger-api
Deep linking for models
For large complex models, it'd be very nice to be able to click on a type that's referenced in some property and have it link to the schema for that type (especially since types aren't displayed in any particular order, so scrolling to find them can be tedious). The current styling actually makes the type names look like links, but they're not.
+1
We need the ability to display JSON models separate from APIs. The use case cares not for paths or HTTP Verbs; simply how the JSON model is structured along with its data types.
Can anyone give an example deeplink to a model from http://petstore.swagger.io/? They don't see to be linkable, as far as I can tell :) Thanks!
Seems models aren't included? https://github.com/swagger-api/swagger-ui/issues/2884#issuecomment-315492951
Can we re-open?
I too would like to see deep links for models. It would be helpful when attempting to refer a customer/partner to a particular section of the documentation.
+1. I was thinking something is wrong with the way I enable Deep Linking in the setup, but it turned out there's no deep linking for model / definitions. Nice feature to have.
+1. It would be very nice to be able to link to these model definitions. My specific use-case is to link request and response models in sequence diagrams to swagger specs.
Weird that this is still not implemented. At least I was not able to find it. Anyways, here's how you can do it:
document.addEventListener("DOMContentLoaded", function (event) {
var elemId = window.location.hash.replace('!/', '').replace('/', '').replace('#','');
setTimeout(function () {
var elem = document.getElementById(elemId );
if (elem) {
var top = elem.offsetTop;
window.scrollTo({ top: top, behavior: 'auto' });
var anchor = elem.querySelector('.model');
if (anchor) {
anchor.click();
}
}
}, 700);
});
This obviously goes into a javascript that you inject via:
c.InjectJavascript("/path/to/your-file.js");
Also remember to enable StaticFiles middleware in dot net core.
+1: If someone would like to implement HATEOAS link relations, they would need to provide a uri to the specification of the object. I would like to use the Model object in Swagger UI for this purpose, with a deep link.
I started implementing the part where it would be possible to expand and scroll to a model by specifying a reference to it in the URL.
I'm curious if anyone would still like to have the original feature request implemented? It was, in my understanding, to be able to navigate to a model definition by clicking that model's name in another model or in an operation definition. If yes, how would you expect it to work? Because currently if you click on a model's name it expands/collapses, so I don't know where would the link navigation fit into this behavior. Any ideas?
@mdhtr Would it be possible to expand only from the > symbol, and have the name as a link?
A non-breaking way for the existing expand/collapse functionality could be to add a link next to the name, with the text "link" / "permalink" / "🔗" or similar.
@PeterKottas thanks for the code! A minor bug, if the model is near the bottom of the page it doesn't scroll down far enough, because the link hasn't been expanded yet and the offsetTop won't be correct after the click. This can be fixed by doing the scrolling after the click:
document.addEventListener("DOMContentLoaded", function (event) {
var elemId = window.location.hash.replace('!/', '').replace('/', '').replace('#', '');
setTimeout(function () {
var elem = document.getElementById(elemId);
if (elem) {
var anchor = elem.querySelector('.model');
if (anchor) {
anchor.click();
}
setTimeout(function () {
var top = elem.offsetTop;
window.scrollTo({ top: top, behavior: 'auto' });
}, 100);
}
}, 700);
});
There's another approach with works with standard HTML mechanisms and does not require extra JavaScript or a patch. It is dependent on the current swagger implementation though and might change.
Every model div and an ID with the pattern model-<SchemaName>. You can directly link to it by adding the ID to the fragment of your URL.
Taking the Petstore example, you can directly jump to Category via the URL https://petstore.swagger.io#model-Category . If you want to add this link within a description of your YAML, you can use <a href="#model-Category">schema</a>
