Definitely check out http://readme.io. Their docs look beautiful and set-up is a breeze.

Thanks for the tip, Tim! Happy to answer any questions folks have about my product.

Also, plugging: Swagger support in just a few weeks. And we can currently auto generate endpoint reference docs from your source code using a commenting standard similar to javadoc.

We get all sorts of excited by good API documentation. Weird, right? Apparently not, based on this thread. :D

I find all of the auto-generated systems produce barely sufficient documentation.

Real documentation is written by a person who understands how to use the API.

Unfortunately, such documentation then suffers bit-rot if it's not updated whenever the API is updated.

What I would like to see is some way to describe an API which can be merged with the hand-written narrative and instructions, and can be refreshed whenever the implementation changes.

We're using swagger to great effect, the ability to add markdown against the endpoints allows us to describe them with both relevant documentation and examples.

http://oi60.tinypic.com/33llco5.jpg

You can try using API Blueprint (https://apiblueprint.org) which is based on Markdown can host your API docs at http://apiary.io

Disclaimer: I work at Apiary

For our corporate API, we the Apiary markdown with aglio to convert into nice documentation. I've tried RAML (I didn't like the giant YAML file) and apidoc (I didn't like to put 100 lines of user documentation next to 20 lines of implementation). I use protagonist to convert the md file to JSON which my Python code can load and compare with the decorated API endpoints -- I can then verify they and all their parameters are properly documented. I don't use the fancy Apiary features yet.

More of a product, but codecademy (http://www.codecademy.com/learn) has a number of APIs it covers how to use.

e.g. http://docs.themoviedb.apiary.io/#reference/collections/coll... where TMDB use apiary, and with quick examples with the different inputs and outputs. So you can test it out right away WITHOUT needing to find ID's to use for test. This provides real response values, as to know what you get when you send some value.