I really liked Swagger years ago, as their documentation format was really nice to write and the results were really amazing. But some time in the past, they decided to remove all collaborative features (i.e. allowing others to edit) and only offer these in their commercial version, which is 15 USD per user per month. That was unfortunate, and as they have no special offer for open source projects, it is kinda dead to me.
These days, for diaspora* or other projects, I’d probably build something based on GitHub that runs ReDoc on Travis and pushes the result into a GitHub pages-served branch or so. That way, collaboration happens on GitHub via PRs with the usual access control flows, but we’d still end up with a nice interactive documentation.
As for generating API clients, I really dislike those tools. They work fine for generic stuff, but they have limits. A good API library is not just returning JSON objects, but is working the data into object structures that match the application design as well as the language they are designed in. This is stuff that needs to be done by hand. I used quite a few of those auto-generated libraries before, and I hated them every single time. It always felt like I was just getting a de-serialized JSON, and while that could be an okay-ish solution for something I built myself, I do not expect this kind of sloppyness from any official API.
For me, I’d rather have no official library and being forced to write a little JSON-requesting machine myself. If i see official API libraries for a project, I expect them to be nice, and not just some autogenerated stuff.