Pronounced like "drought", with an "s" on the end.

Rails has this nice rake task, routes, which is great for server developers to check which routes go where, but it's not very appropriate for client developers. Since I do a lot of work with client engineers I wanted a way to generate client-friendly REST documentation based on the application routes. I then added YARD into the mix, my personal favorite documentation tool, and came up with droutes, or documented routes.

Because it uses YARD as the underlying documentation parser, anyone familiar with YARD can quickly and easily begin creating client integration documentation.

Every controller is inspected by droutes, and a matching route config is found. If you have a controller and action for something, but no route pointing to it in config/routes.rb, then no documentation is generated for it.

YARD is used to parse the controller file. The output generated assumes that is action uses the @param tag to reference a request parameter. Remember: in Rails, request parameters may come from both the request body and the URL.

For example, if I wanted to document a request parameter called id, used in the route GET /posts/:id, I would use YARD to capture it as so:

@param [Integer] id the id of the post to view

The droutes gem adds a rails generator instead of a rake task, as running the operation from the generator ensures the Rails app environment is loaded and that all the routing data is available. Without the routing data, the document generator would not be able to gain information such as request method (e.g. POST) or path (e.g. /posts/:id).

rails g droutes:documentation

That's it. This will generate a folder .droutes that contains HTML output. Each controller gets its own HTML file, and the index contains a sorted list of all routing paths available.