Discourse API Documentation Using RAML

(Sawood Alam) #1

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.

(Blake Erickson) #2

Great idea :wink:

The API Docs are currently being re-written in YAML which ReDoc uses to display the results.

(Erlend Sogge Heggen) #3

See https://docs.discourse.org and: