How can we improve the API documentation experience?

Currently the Swagger UI is used to document endpoint, but it might be better to "colocate" the docs with the code, and "send" that to swagger (if possible).

Investigate what's possible and what a nice Developer Experience (DX) might look like.