Rails with rake-test
Add --format documentation to rspec
Basic passing specs with rack-test
DRY: Extract Accept application/json
DRY: Extract Respond with application/json
DRY: respond_with to assert status and body
DRY: JSON parse response body
Invert request and it following rspec_api_doc syntax

Notice that I'm using my branch that sets parameters to {}
more compact rsp-api-doc format with :id

I can justify this step saying that it's fine that we have to specs but
wouldn't it be great if this also served as documentation? Enter rspec
api doc. First make a commit WITHOUT grouping by /:id but only by
generating and showing the docs. Then add this nice thing
Better doc titles
Make tests more meaningful, less dependent on fixtures

now the problem with this test and documentation is that we are testing one
specific case, depending on the exact fixtures above! It would be much better
if you could tell our users what to expect IN EVERY CASE, not just with these
given fixtures. So they know for instance how to parse it. What do they get?
A JSON, sure, but is it an array? Or a hash? Which keys does it include? Which
types are the values in? All this information is very valuable to API clients,
and also if you know this, we can have tests that ensure that what we promise
to our clients is actually what happens. So let's start by the INDEX. We
don't need to test that the exact parsed JSON is [{"where"=>"Coachella", "year"=>2013}, {"where"=>"Woodstock", "year"=>1969}]
This is not very valuable or intuitive as a description, and the test is
dependent on the fixture. But what we can test (and describe) generically is:
1) we will return (in JSON) an ARRAY
2) each array item will be (in JSON) a HASH
3) each item will have the key "where" and a String
4) each item will have the key "year" and an Integer or nil.

Then, just specific to the fixtures above, we can check the size
Same thing for all the tests
DRY: Expect Hash or Array
we introduce has_attribute :where, String which means that
every request that returns resources Concert will always
have a key 'where' of type String (either in hash or array).

This is a very good documentation, and we also test it
automatically every time
Same with when, with the additional option that it can be nil
check attributes on every success with content, even without block

https://github.com/rails/rails/pull/7231/files
Use short codes for HTTP status
Move attributes in own helper
Move instance creation into helper

How to make this spec even more generic and good for documentation?

Let's talk about that not_to be_empty check. What exactly do we mean?
We mean that if we have some concerts in the DB then /concerts should
not be empty. Does not matter their content. Now, if we didn't have
them, the rest of the test would still pass, because it would check the
attributes of NOTHING. But then it wouldn't be a meaningful test. If
suddenly we changed the attributes, the test would not fail! In other
words, it is really IMPORTANT that whenever we run the test for INDEX
we do have SOME instances in the DB, otherwise we are not fully testing.
And even in the documentation, we would not have any example output.
In general, testing with NO items in a DB is just a subcase, we do want
elements so we can fully test. So we can write this:
First use of instances: .count