search

matrix-org / matrix-spec

The Matrix protocol specification
Apache License 2.0
193 stars 96 forks source link

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

Open ara4n opened 6 years ago

richvdh commented 6 years ago

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

ara4n commented 6 years ago

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

Half-Shot commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 1 year ago

I guess this is going to be better once https://github.com/matrix-org/matrix-spec/issues/331 is fixed