Operation & Tag Deep-linking Support

[STRML]

Shebang support is no longer present on operations in 3.x as noted in the docs. This feature was present in 2.x. I found no open issue tracking its release in 3.x so I thought it best to open one.

[webron]

https://github.com/swagger-api/swagger-ui#known-issues

[STRML]

Yes, I'm aware: see as noted in the docs in the OP.

[shockey]

@webron, before I mark this as Ready, can you give me a summary of how we want this to work in 3.x? Thanks!

[webron]

We don't have to use a shebang, hash should be enough. The goal is to have permanent links to tags or operations in the UI.

• When clicking on a tag or operation to expand it, the browser url will change to the new url permanently linking to that tag/operation.
• The link will also be available when right clicking the tag/operation and copying the link url.
• Collapsing a tag/operation will change the URL back to the top-level swagger-ui URL.
• Opening the link directly in the browser will have the browser load the spec, and that linked tag/operation would be expanded.

Because operations can exist under multiple tags, the unique URL should be a combination of the two.

In the petstore example:

• Clicking the 'pet' tag would generate the link http://petstore.swagger.io/#/pet
• Clicking the POST /pet operation (with operationId addPet) will generate the link http://petstore.swagger.io/#/pet/addPet

The URL structure (slashes, hash) can change, as long as the spirit is the same.

[heldersepu]

I would like to add one more item to the list of permanent links from @webron

• In the response section (responses-wrapper)

There is also valuable information there and on a few occasions I had to refer customer to that section, a way to direct link there would be awesome

[heldersepu]

Also it will be nice if the URL structure (slashes, hash) is backwards compatible with 2.x
That way swagger users can upgrade without having to revisit hundreds of documentation pages and blog posts

[shockey]

will be nice if the URL structure (slashes, hash) is backwards compatible with 2.x

I agree - keep in mind it's possible to generate the URLs as proposed, and still interpret the legacy URLs correctly.

[webron]

@heldersepu for linking to specific sections (responses, or others), please file a separate ticket with the relevant details.

As much as we'd like to offer backwards compatibility in general, it's unlikely to be here (and this is a major version). We're likely to use hashes in this version, for example, as opposed to shebang.

[shockey]

This is now implemented - please note that the functionality must be enabled explicitly by passing deepLinking: true to Swagger-UI.

[fehguy]

👍

[shockey]

@heldersepu, I know this was a big blocker for you getting Swashbuckle moved up to 3.x, so CCing you here 😄

[fehguy]

then + @domaindrivendev who leads that project!

[heldersepu]

looking good:
http://swashbuckletest.azurewebsites.net/swagger/ui/index#/RoutePrefix
http://swashbuckletest.azurewebsites.net/swagger/ui/index#/RoutePrefix/RoutePrefix_PostTest1

Love it!
not sure why is not the default ...
but I have no problem adding the deepLinking: true

[shockey]

@heldersepu, I made a note about that here: #3388 (comment)

Glad to see it's working well!

[heldersepu]

Are the models supposed to be working too?

On mouse over there is a #/definitions/model_name showing...

[shockey]

@heldersepu, models are not included in this feature (they're much less commonly linked to, in our experience).

You're seeing the tooltip that indicates the model's path in the spec, which is useful when one is writing a $ref that points to a model.