[prodikl]

> The rest of the URIs are provided by Hypermedia.

I know this sounds awesome but in practice, it's really useful to have my swagger UI exposing the endpoints for our front-end developers to consume. What a pain it'd be for me to tell them "hit / and see what you get!"

Having HAL links between resources is great and this discovery aspect of HATEOAS makes a lot of sense in development. But having a single entrypoint "homepage" to the API, when it comes to swagger, doesn't make sense.

I ran into this when I asked another department for the endpoint to hit for certain data. I was given a swagger page with a bunch of "/status" endpoints that would then reveal additional endpoints. Who knows what rabbit hole I was sent down. I just needed the endpoint and the necessary parameters.

If I were a third party or some outside developer consuming the API, it kind of makes sense. But our internal swagger docs really should reveal endpoints. I would feel like a big asshole if I asked my front-end co-worker to just "hit /status" and see if you get what you need!

Disclosure: I don't use Swagger codegen. I only use the Docblock markup to document my API and generate the swagger.json that I display on our docs page.