All ids and names are missing in swagger spec html

[webron]

From @jvivs on April 29, 2016 15:8

Swagger.io is currently the place where most of my coworkers go to read the OpenAPI spec and the linking structure appears to have changed. It's frustrating to have links break, especially when you're trying to link to someone in a document as long as this one: http://swagger.io/specification/

Is it possible to add github-style linking to headers like the markdown file has on github? Also if there are anchors internally in the document, can we have an index or at least put some text in them so they can be found without having to view the source code?

I can open a PR if it is welcome.

Copied from original issue: OAI/OpenAPI-Specification#675

[webron]

This is unrelated to the spec, and the anchors are there. For example - http://swagger.io/specification/#operationObject.

[jvivs]

There's no way to actually use them in the context of the document unless you inspect the source. It's a pretty crummy user experience.

Taking the current markup:

<h4><a name="operationObject"></a>Operation Object</h4>

It would be great for the anchor wrap the text and have a self-referential href as well:

<h4><a name="operationObject" href="#operationObject">Operation Object</a></h4>

[webron]

It's a rendering issue, not a spec issue, and should be handled by our rendering engine in the site. The github renderer is different and does it automatically.

[ePaul]

If we are talking about the rendering engine, would it be possible to have it also generate a table of contents?

[webron]

@ePaul - unlikely for now, I'm afraid. 3.0 should have it as part of the spec itself (hopefully).