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
DRY: Take resource name from example
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
This is the most complicated specs

We want to write code in a readable way but evaluated things in the
inverse order. We write "given_some_instances" outside of the examples
but they are "before" inside each example. But then we write the
lazy params before, and we want them to be evaluated after the before.

So it's all about Proc and instance_exec.

Note that request_params.dup is there because the do_request consumes
the parameters, but we want example.metadata[:request_params] to remain
the same inside the example
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
Test for new /locations/:location/concerts

We want a new API response to filter concerts by location, but
passed as lower case in the URL. It's a required parameter
Add routes for /locations/:location/concerts
Rails app code to make filters work
DRY: new request_params method