RAML – RESTful API modeling language

There's also the swagger spec:

http://swagger.io/

Very cool, it feels like WSDL for REST

EDIT: spelling

Are any of those projects open source? I'm looking for an example Swagger YAML/JSON file that includes authentication.

I wrote some RAML recently and found it very good for creating a machine-readable representation of an API. We also wanted to make it human-readable and use it as our API reference (with the API console). I found it to be mostly good, but had some trouble when explaining larger concepts that span several requests. Also, it's harder to point to the "important" parts of the API if it's sufficiently large than it was with our "freeform" reference.

I haven't looked into Swagger deeply, but RAML seems better at re-usability. Swagger seems to have way more traction though, and also more tools.

I wrote a Python parser for this called RAMLfications (https://ramlfications.readthedocs.org/en/latest/)

I actually built the API console for my company - Spotify (https://developer.spotify.com/web-api/console/) - based off of RAML and am in the process of open sourcing the tech behind it. The first bit being RAMLfications, and the second, called Griffin (https://github.com/spotify/griffin) is a super alpha version of a static doc generator based off of RAML. The next/last bit to open source is the console itself, as well as some integrations like Flask extensions/Django packages.