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

[webron]

Why not both? The description field at that level is meant to describe the "response". HTTP codes are self explanatory, so in most cases you need to describe what they mean. However, in the example you provide, you can just say:
"The foo has been received and will be processed within one minute. The response value can be used to inquire about the status of processing of the foo.". Now, we do find the majority of cases where the response value is indeed a JSON object, and then the schema describing it more easily. If you do want to separate things like in your example, you can use that structure, only there's no need to specify type there because that's not really usable information.

[AndreKR]

Yes, I'd definitely want to keep them separate. If I wanted to find a description of the response value and the description started with "The foo has been received ..." I'd immediately stop reading because I'd think "oh, this is about the status code, so it's irrelevant".

I'd happily change my API to wrap the response value in a JSON object if that makes it easier to document.

I still think the spec should clarify if "A description of the response" means a description of the status code or of the response value, unless it is actually meant to contain both, which I'd dislike but I can respect.

[handrews]

Since @webron answered that it is indeed intended to describe both, I'm going to close this as resolved.