Decouple request/response serialisation from example pairs

[kylef]

After looking at #16 I was thinking about the possibility to decouple serialisation formats from the examples themselves. This allows you to define the serialisations the API supports in one place and then the examples would be serialised into the supported formats. This feature would be similar to the produces and consumes feature in Swagger.

This would allow us to declare upfront that application/json can be produced for all responses, and that application/json can be consumed in all applicable request bodies. In Swagger this can also be overridden for specific paths or operations in an API.

As an example, this feature could be mapped into API Blueprint as follows. Where I can declare that my API both produces and consumes application/json. However for the OAuth2 flow, we only support application/x-www-form-urlencoded and thus in an Authentication group we can override the produces and consumes to be application/x-www-form-urlencoded.

# My API

+ Produces
    + `application/json`

+ Consumes
    + `application/json`

## Users [/user/{username}]

### View a User [GET]

+ Response 200
    + Attributes (User)

## Group Authentication

+ Consumes
    + `application/x-www-form-urlencoded`

+ Produces
    + `application/x-www-form-urlencoded`

### Exchange a Refresh Token [POST /token]

+ Request
    + Headers:
        + Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

    + Attributes
        + `grant_type`: `refresh_token`
         + `refresh_token` (Refresh Token)

+ Response 201

I could also provide multiple content types that I support and then example request and response pairs can be created for all permutations.

## GET /users

+ Produces
    + `application/yaml`
    + `application/json`
    + `application/xml`

+ Response 200
    + Attributes (array[User])

In the above example, I would declare a /users resource with a GET action that produces YAML, JSON and XML based on content negotiation. I declare an example response that would be available in both YAML and JSON without having to write that for each serialisation:

## GET /users

+ Response 200 (application/yaml)
    + Attributes (array[User])

+ Response 200 (application/json)
    + Attributes (array[User])

+ Response 200 (application/xml)
    + Attributes (array[User])

This was just an idea, opened issue for some discussion before time is spent on writing an RFC.