I didn't downvote, but I'm thinking that you need endpoint discovery, bucket types, etc. Sure you could write a 1 page document describing the buckets at the root level, the relationships of the objects, etc., but why not let swagger do that for you at compile time?

Not one of the downvoters, but I'd guess it's because this is only true with HATEOAS which is the part that 99% of teams ignore when implementing "REST" APIs. The downvoters may not have even known that's what you were talking about. When people say REST they almost never mean HATEOAS even though they were explicitly intended to go together. Today "REST" just means "we'll occasionally use a verb other than GET and POST, and sometimes we'll put an argument in the path instead of the query string" and sometimes not even that much. If you're really doing RPC and calling it REST, then you need something to document all the endpoints because the endpoints are no longer self-documenting.

Self documenting, but mainly to the architect who put ‘RESTful’ in the slide deck and called the documentation done.