I am proposing the Discourse API documentation using RESTful API Modeling Language (RAML). This would enable us to:
- programmatically interact with the API
- perform testing on various endpoints
- automatically generated interactive interfaces to read the documentation
- maintain the API docs along with the code
There are various tools including API Console to make the RAML documentation available online and allow user to interact with a live endpoint.
Recently I wrote a tool called MemGator to aggregate archived versions of any URI from various archives in a single place. The tool can be used from the command line or as a web service. To document the web service API endpoints I used RAML which can be seen in action at MemGator Server API. It includes live Try it fuctionality as well.
RAML has the familiar YAML syntax and is quite modular and composable, so it should be very easy to organize each endpoint in separate files and have shared logic and examples in appropriate directory structure.
