Swagger yaml is hard to write? Hmm.. relative to the code that services it or consumes it, I find its pretty trivial.
Exactly. I wrote a project (https://github.com/EverythingMe/vertex) where you define the API with a semi declarative syntax in Go, and it just translates to swagger so you can generate documentation and playgrounds effortlessly. It worked very well.
I believe the best use-case for Swagger is to develop the API (perhaps just defining the routes with payload and response, but without controllers), and then auto-generating the Swagger files. This way the API consumers always have an up-to-date documentation, and there is only one place which represents the current state of the API.