Problem description

Clarifications proposed by @PedroDiez in PR #441 for new API Design Guide document

All requestBody attribute must have a description. They will have one of the following structures:
Case A: Request body structure is explicitly detailed. Usually when the request body is not reusable among different operations.

      requestBody:
        description: <description>
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/<schema-name>"
        required: true

Case B: Request Body structure is referenced to an schema in components.requestBodies. Usually when the request body is reusable among different operations

     requestBody:
       $ref: '#/components/requestBodies/<schema-name>'

Responses:

All response objects must have a description. They will usually have the following structure:

Success response codes: their structure is explicitly detailed.
Error response codes: their structure is referenced to an schema in components.responses

      responses:
        "2xx":
          description: <description>
          headers:
            x-correlator:
              $ref: "#/components/headers/x-correlator"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/<schema-name>"
        "4xx":
          $ref: "#/components/responses/<schema-name>"
        "5xx":
          $ref: "#/components/responses/<schema-name>"

Expected action

Agree on proposed clarifications

Additional context