[Question] How to describe different responses within same action

[kurko]

Say I have multiple responses in an action like the following:

### Creates a user [POST]

+ Request
    + Body
        some_body_not_relevant_now

+ Response 201 (application/json)
    + Body
        {"id":"1", "name": "John Doe", "email":"john@doe.com"}

+ Response 422 (application/json)
    + Body
        {"errors":[{"detail":"Email must be unique"}]}

+ Response 422 (application/json)
    + Body
        {"errors":[{"detail":"Name cannot be blank"}]}

See those Response 422 there? I need to describe them somehow so the user has an idea about their context. I could create a paragraph right after ### Creates a user [POST], but I'm wondering if the spec somewhere allows me to do something like the following (I couldn't find it):

When a duplicated email is sent <----
+ Response 422 (application/json)
    + Body
        {"errors":[{"detail":"Email must be unique"}]}

When name is not sent <----
+ Response 422 (application/json)
    + Body
        {"errors":[{"detail":"Name cannot be blank"}]}

How do you do when you have a lot of example requests? Thanks.

[kylef]

@kurko You can provide a description for the request that produces the response.

For example:

# My API

## User [/user/{username}]

+ Parameters
    + username

+ Attributes
    + username: Kyle (required)
    + email: `kyle@apiary.io` (required)

### View a user [GET]

+ Response 200 (application/json)
    + Attributes (User)

## User Collection [/users]
### Create a new User [POST]

+ Request (application/json)
    + Attributes (User)

+ Response 201 (application/json)
    + Attributes (User)

+ Request A request with an invalid name (application/json)
    + Attributes (User)
        + username

+ Response 422 (application/json)

        {"errors":[{"detail":"Name cannot be blank"}]}

+ Request A request with a used email address (application/json)
    + Attributes (User)
        + email: `used@example.com`

+ Response 422 (application/json)

        {"errors":[{"detail":"Email must be unique"}]}

This could be rendered as follows:

[kurko]

Yeah, ok. That is a really small description. I was willing to have something longer. I guess I can just use the HTTP method description to include details about specific requests.