DSL Redesign

We have been using this DSL for a while, and we have found a number of shortcomings:

• The DSL is monolithic, making it hard to test and extend
• You are forced to write all your assertions in one example
• It's too diverged from standard RSpec syntax, and should feel more familiar

I hope that everyone can participate in this discussion to make RspecApiDocumentation better and easier to use. If you would like to participate in this discussion, please add your comments to the END of the document and sign with your name. If necessary, separate your comment with an horizontal rule. If you are familiar with c2 wiki, it's just like that.

-- Sam

---

Here is a starting point for discussion about the new DSL:

# We should be able to use shared contexts and shared examples,
# because "It's just RSpec."
shared_context :json do
  header "Accept", "application/json"

  it "should return a JSON file" do
    response_headers["Content-Type"].should eq("application/json")
  end
end

shared_context :xml do
  header "Accept", "application/xml"

  it "should return an XML file" do
    response_headers["Content-Type"].should eq("application/xml")
  end
end

shared_examples_for :ok_request do
  it "should have status 200" do
    status.should eq(200)
  end
end

# Resources are defined the usual way.
resource "Gems" do

  # Instead of creating one document per example, create one document per endpoint context,
  # e.g, the following. We require users to provide the document title here as well.
  get "/api/v1/gems", "Listing all of your gems" do

    # If a HTTP context includes contexts, we will show them all as part of the same document.
    # Imagine tabs or an accordian widget or similar.
    context "JSON" do
      include_context :json

      it_should_behave_like :ok_request

      # more assertions
    end

    context "XML" do
      include_context :xml

      it_should_behave_like :ok_request

      # more assertions
    end
  end

  # It's perfectly fine to create another document for the same endpoint. Here we show
  # what it might look like to document the case where query parameters are provided.
  # The rubygems.org api actually uses a /api/v1/search endpoint for this...
  get "/api/v1/gems", "Searching your gems" do
    parameter :query, "A single term that will be compared to your gems' names"

    required_parameter :query

    let(:query) { "api_doc" }

    context "JSON" do
      include_context :json

      it_should_behave_like :ok_request

      # more assertions
    end
  end
end

---

At RailsConf Sam and I came up with the following DSL:

https://gist.github.com/ca8dee943b36237d8109

-- Eric

---

Eric, your example uses "request" where mine has "context." I support making request an alias to context. Also, that gist still shows a scenario object yielding from the endpoint contexts, which I think is an oversight. --Sam