Make it more obvious that the spec is the primary resource, not the swagger viewer

[ara4n]

No description provided.

[richvdh]

... why? people should be able to use the swagger if they like - it gives a better overview of the API.

[ara4n]

you lose all the verbiage?
it's great as pure API reference, but not as a substitute for the spec itself.

[Half-Shot]

Agreed on this one. There are many little details the swagger UI omits that creep up on you. Besides, the spec doc isn't a horrific read.

[richvdh]

To be clear: what I am keen to avoid is a banner across the top of the swagger viewer saying "this is a lie, go and read the spec instead", as that would be an indication that we have failed with the swagger viewer. It sounds like that's not really what was proposed, however.

I would certainly support having links from the API descriptions to the relevant bits of the spec - though I'm not sure (a) what the mechanics are of getting the swagger viewer to display useful links, and (b) given that the description appears in both the viewer and the spec, how we achieve this without making the spec nonsensical.

[Half-Shot]

Could we go halfway and have a link saying "for a more detailed and technical document, please see the CS API. We don't need to explictally or even remotely imply that "Swagger is bad. Do not use".

Doesn't have to be a big red banner or anything, just suggested reading.

[KitsuneRal]

Instead of banners of any kind, I'd really appreciate links from specific parts in the description to the respective topics in The Spec. And I'm totally fine to have duplication across those. Linking from descriptions is a matter of OpenAPI 3, though?

[richvdh]

Instead of banners of any kind, I'd really appreciate links from specific parts in the description to the respective topics in The Spec

Yes, this is what I am arguing for.

Linking from descriptions is a matter of OpenAPI 3, though?

Well, OpenAPI 3 is a thing we should have anyway.

[richvdh]

I guess this is going to be better once #331 is fixed