rspec_api_documentation dsl changes

gistfile1.rb

resource "Orders" do
  let(:client) { RspecApiDocumentation::RackTestClient.new(self, :headers => { "Accept" => format }) }

  get "/orders", "Listing orders" do
    request "XML" do
      let(:format) { "xml" }

      it "should have the correct header" do
        response_headers["Content-Type"].should == "application/xml"
      end

      it "should have the correct status" do
        status.should == 200
      end

      it "should have the correct body" do
        response_body.should match(/my expectation/)
      end
    end

    request "JSON" do
      let(:format) { "json" }

      it "should have the correct header" do
        response_headers["Content-Type"].should == "application/json"
      end

      it "should have the correct status" do
        status.should == 200
      end

      it "should have the correct body" do
        response_body.should match(/my expectation/)
      end
    end
  end

  post "/orders", "Creating an order" do
    parameter :name, "name of order"
    parameter :size, "Size of order"

    required_parameters :name

    let(:name) { "Name of order" }

    request "XML" do
      let(:format) { "xml" }

      its(:status) { should == 201 }
    end

    request "JSON" do
      let(:format) { "json" }

      its(:status) { should == 201 }

      it "should have the correct information" do
        response_body.should be_json_eql({:name => "Name of order"}.to_json)
      end
    end
  end

  get "/orders/:id", "Viewing an order" do
    let(:id) { order.id }

    request "Someone else's order" do
      let(:format) { "json" }
      let(:id) { create(:order).id }

      its(:status) { should == 403 }
    end
  end

  delete "/orders/:id", "Deleting an order" do
    let(:id) { order.id }

    its(:status) { should == 200 }

    request "Someone else's order" do
      let(:id) { create(:order).id }

      its(:status) { should == 403 }
    end
  end
end

One thing I would like to see in the new DSL is an easy way to test payload differences between different requested versions. Right now I have to state in each block multiple header 'Accept', 'application/vnd.company.json;version=1' statements. I wonder if you can do something like define the version scheme at the top of the file like

let(:base_version) { |x| {headers: {"Accept" => "application/vnd.company.json;version=#{x}"}} }

request "version 1 of someone's order", version: '1' do
  ....
end

I'm wishing for it() blocks to optionally contribute to the endpoint description, so that the same examples that prove the functionality also describe it for documentation purposes.

Without bloating the sample generated in docs with the detailed evidence.