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
Another use: create
Failing idea on using instances.any :id

Explain that "before" is actually run after "example_request", so
this fails because by the time we call instances.any :id, the before
has not been called yet.

You can try by writing debugger both in the before and in the .any

Also, I move the setup_instances inside the example, without before
Add instance.none and expand to all examples

Now look at the get '/concerts/:id' example, isn't it pretty?
Assign random value to attributes

Now the only thing left hard-coded are these instances. What is bad about
this? Two things: we are writing tests for VERY SPECIFIC cases in the
database, and also our documentation will ALWAYS show these examples, as
though these were the only things ever returned by our API. But actually
we can express this in a more meaningful way. All we need is to create
some instances where the attributes have any random value for their type.
And we already know the types, they are in our attributes list! And not
only that, but we also know which attributes can be nil, so for those
we don't even have to always set a value (year). So we can write the
following (note that for now, one instance is enough for all tests)

Now, run rspec and look at the log and you will see random values!
Rerun rake docs:generate to see new values

It's better because they are random... it would be even better to
just show in the documentation the TYPES that we expect, will do later
DRY: use symbols for types
Don't always assign values to attributes that can be nil