I'm using aglio to generate my API documentation. I'm currently writing the raw markdown for this based on the API Blueprint spec. I'm wondering if there's a way to generate the markdown via comments directly in the code. Is anyone aware of a way to do this?
Technically it is possible. Depending on your language and used frameworks. For example, in Ruby, one could use RSpec to generate API Blueprint.
I am not familiar with any tool that does something similar for Node.js (e.g. using Express.js DSL).
When writing a tool that is generating a blueprint, one can avoid authoring the blueprint manually and use Matter Compiler instead. This tool (Ruby gem) converts JSON or in memory tree (AST) into API Blueprint.
Note that I personally advice against generating documentation from the code. Instead I consider API Blueprint as a contract that can be used to test your API implementation.
In this sense generating a blueprint from the code is like generating tests from the code (to test the very same code).