Discourse API Documentation Using RAML

Development

AI-generated summary

The proposal is to use RESTful API Modeling Language (RAML) for Discourse API documentation. This would allow for programmatic interaction, automated testing, and interactive interfaces. RAML also enables maintaining API documentation alongside code. ibnesayeed shares their experience using RAML for the MemGator tool and its API documentation, which features live “Try it” functionality. The proposal is well-received, with blake expressing support. Note that the API Docs are currently being rewritten in YAML, which is used by ReDoc.

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.

2

Great idea :wink:

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