Maintaining API docs can be a real pain, and a lot of people overlook them, especially when it is purely an internally-used service.
I've discovered a few nice tools that generate pretty docs based on markdown files, but I haven't found anything that automates the process of maintaining the actually content.
I was thinking about how to do this, and I think it would be really cool if there was some sort of DSL or library for automating JSON API docs via integration tests on your controllers.
For example, you might have a test like this that creates a new blog post:
test "create a post" do
"title" => "My first post",
"body" => "Some content...",
"inserted_at" => _,
"updated_at" => _
|> post("/posts", title: "My first post", body: "Some content...")
And then some mix task would automatically generate documentation based on your tests.
Does anyone know if something like this already exists?