We have been using Swagger and developed a REST API library [1] in Java that automatically generates Swagger specification for your API using static analysis. We can also automatically generate client libraries (https://github.com/buremba/rakam-client) and API documentation (http://api.rakam.io/) from Swagger specification. Currently, the library lacks documentation but it can at least give you the idea.
The latest version of Swagger Codegen (https://github.com/swagger-api/swagger-codegen) also automatically generates documentation (markdown) for API clients/libraries, e.g. installation, getting start, doc for API endpoints and models.
Nice! Instead of generating Markdown files, you could also generate full HTML documentation similar to Slate. The generated Markdown files can be used in Slate since the format seems to be similar. Actually I opened an issue in swagger-codegen repo (https://github.com/swagger-api/swagger-codegen/issues/1387) and we talked about it. The reason that I created a separate project is that the the example usage section and the format didn't seem to be implemented as language in swagger-codegen.
I notice that you put all the clients (C#, Java, Ruby, PHP, etc) under the same Github project.
I would suggest you to create separate Github repo for API clients in different languages so that developers can install the PHP, Python, Ruby, etc API clients directly from the Github repo.
You can leverage "git_push.sh" to push the auto-generated SDKs (with doc, sample code) to Github.
is there a good example of an OPEN SOURCE REST API?
I would like to see how the versioning is achieved, how the versions are incremented, etc?
Bonus points if it is in the Java ecosystem.