Specification website improvements

[Mahoney]

Hi,

I'm finding the online specification a little frustrating. A few things:

1. It has lots of anchor tags, which is great, but ECMAScript is being used when you click on them which means that the browser's URL doesn't update and the back button doesn't work. As the browser will handle anchor tags out of the box ECMAScript is purely making things worse here.

2. When you click on an anchor tag the floating top nav bar obscures the Heading that you navigated to, so you are unsure whether you are in the right place

3. If you disable ECMAScript then the yaml/json snippets become white text on a white background

What's the right place to raise these?

Thanks!

[MikeRalphson]

Hi, this is a fine place to raise these points. We use ReSpec to render the markdown to html so we are a little stuck with how it works. One thing we may be able to do is upgrade the ReSpec version if there are bug-fixes or new features added which we could make use of. Could you compare our spec with the ReSpec docs page and see if your issues exist there?

[flaksp]

You may browse the specification at the official website: https://spec.openapis.org/oas/latest.html

It supports anchors in a sidebar, back/forward buttons work fine, and it looks much cleaner in my opinion than Swagger website.

[MikeRalphson]

Thank you @flaksp ! I assumed the OP was referencing spec.openapis.org, and didn't actually follow the link.

The documentation at swagger.io, while containing some fine sidebar content, is not the official spec.

[Mahoney]

Ah! Apologies, that's a much nicer site. Thanks for the pointer.