Proposal for Weasel Diesel's DSL: describe different scenarios for a given response, including support status codes and headers

api.rb

# Based on http://developer.github.com/v3/gists/#check-if-a-gist-is-starred

describe_service "/gists/:id/star" do |service|
  service.http_verb :get

  # documentation
  service.documentation do |doc|
    doc.overall "Check if a gist is starred"
    doc.example '<code>curl http://localhost:9292/gists/:id/star</code>'
  end

  # input
  service.param.integer :id, required: true, doc: "The gist id"

  # output
  service.response do |response|
    response.when do |scenario|
      scenario.description "gist is starred"
      scenario.status 204
      scenario.header 'X-RateLimit-Limit', 5000
      scenario.header 'X-RateLimit-Remaining', 4999
    end
    response.when do |scenario|
      scenario.description "gist is not starred"
      scenario.status 404
      scenario.header 'X-RateLimit-Limit', 5000
      scenario.header 'X-RateLimit-Remaining', 4999
    end
  end

  # implementation
  service.implementation do
    # ...
  end
end