Not able to implement Prefer header behavior.

[rmedaer]

The RFC7240 (Section 4.2) defines how-to indicate to the server the preferred representation to return.

• Either a minimal one: no content, a Location header with URI of full resource representation.
• Or a representation: returns the resource in response content, (optional Location header?)

I implemented this behavior in my API. But I would like to specify it in my OpenAPI specification.
This is the current specification I wrote:

paths:
  /resources:
    post:
      operationId:  createResource
      parameters:
        - name: Prefer
          in: header
          description: Preferred representation
          required: false
          style: simple
          explode: true
          schema:
            type: object
            required:
              - return
            properties:
              return:
                type: string
                enum:
                  - representation
                  - minimal
                default: representation
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/newResource"
      responses:
        201:
          description: The resource was created successfully.
          headers:
            Location:
              description: The URI of created resource.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/resource"

Although this is not 100% correct. Indeed, because I'm not able to specify multiple responses with the same code, I can't define the two behaviors depending on Prefer request header.

Btw I don't need to express the "switching" Prefer behavior, but at least I want to express the two possible behaviors/responses.

Maybe related to: #1572

Any thoughts ?

[erunion]

Your parameters array looks off. It should be:

parameters:
  - name: Prefer
    in: header
    description: Preferred representation
    required: false
    style: simple
    explode: true
    schema:
      type: object
      required:
        - return
      properties:
        return:
          type: string
          enum:
            - representation
            - minimal
          default:
            representation

[handrews]

@rmedaer Since you don't need to correlate the Prefer values, you could just make the response schema

oneOf:
  - type: string
    maxLength: 0
  - type: object
    required: [..]
    properties: {...}

[rmedaer]

@erunion indeed ! Wrong copy/paste from $ref. I edited the comment ;-)

@handrews well ! Sounds good to me, thank's.
And if I want to "correlate the Prefer values", do you have an idea how to do it ?

[handrews]

@rmedaer The Preference-Applied response header is how you do it in the message, but since headers and bodies are handled separately and you only get one response object per status code, I don't see any way to correlate it. But I might be missing something.

[handrews]

You could do an enum for the header and, in this case, it's pretty obvious which header value corresponds, but that's definitely not automatically enforced by anything.

[darrelmiller]

@rmedaer Create one schema that validates both minimal and representation as Henry suggested and then create two examples and use the key of the example to identify the minimal vs the full representation example.

[rmedaer]

Looks good to me.

Many thanks