Like others, I use the Apiary's Markdown format, using aglio to generate a HTML page from it. I also use Protagonist to convert the documentation to a JSON object that Python code can consume and verify that there's a 1:1 relationship between documented and implement API endpoints, as well as as arguments passed. There's room for further validation as my API endpoints have type checking and permissions declaratively configured (via Python decorators).
I tried RAML -- it makes sense for quick prototyping of your resources and methods, but I oculdn't see myself writing too much documentation as a giant nested YAML document.
I also tried apidoc which might make sense of you have internal documentation you wan to quickly expose. However my docs are longer than the code implementing them, so I don't like mixing them in as e.g. apidoc would require. I'd prefer lots of English in my documentation and it seems odd to conflate hints on how to use an API call as an external user with the implementation of it. Compare Sphinx-generated Python docs with some auto-generated python library documentation.
The apidoc versioning system is pretty cool, though if you are making a public REST API backwards-incompatible version changes should be avoided.
I tried RAML -- it makes sense for quick prototyping of your resources and methods, but I oculdn't see myself writing too much documentation as a giant nested YAML document.
I also tried apidoc which might make sense of you have internal documentation you wan to quickly expose. However my docs are longer than the code implementing them, so I don't like mixing them in as e.g. apidoc would require. I'd prefer lots of English in my documentation and it seems odd to conflate hints on how to use an API call as an external user with the implementation of it. Compare Sphinx-generated Python docs with some auto-generated python library documentation.
The apidoc versioning system is pretty cool, though if you are making a public REST API backwards-incompatible version changes should be avoided.