Clarify response description

[AndreKR]

It is currently unclear whether the paths.<path>.<method>.responses.<status code>.description field describes the status code or the response body and if it's the status code where to describe the response body and vice versa.

For example both of these seem to be reasonable definitions:

paths:
  /foo:
    post:
      summary: Create a new foo
      responses:
        202:
          description: The foo has been received and will be processed within one minute
          content:
            text/plain: {}

paths:
  /foo:
    post:
      summary: Create a new foo
      responses:
        202:
          description: A job token to inquire about the status of the processing of the foo
          content:
            text/plain: {}

In the OpenAPI Guide on swagger.io the Describing Responses page uses description to describe the response body, except in the section "HTTP Status Codes" where it is used to give a reason for the status code. (Unless I'm missing something and those are actually different description fields.)

[AndreKR]

This might be the appropriate way?

paths:
  /foo:
    post:
      summary: Create a new foo
      responses:
        202:
          description: The foo has been received and will be processed within one minute
          content:
            text/plain:
              schema:
                type: string
                description: A job token to inquire about the status of the processing of the foo