In OpenAPI 3, how to document that an Accept header with a specified value is necessary on request in order for a successful API call?

Question

For a legacy API that I document in order for a successful authentication I need to provide the following headers:

X-Access-Token: {token}
Accept: application/json; version=public/v2

For the token part I need document it via:

openapi: 3.0.0
info:
  version: "v2"
  title: Company App Public Api
  description: Integrate your platform with company app website

components:
  securitySchemes:
    ApiKey:
      type: 'apiKey'
      in: 'header'
      name: 'X-Access-Token'
security:
  - ApiKey: []  

But how I can document that also for an authentication I need to provide an Accept: application/json; version=public/v2. The Accept header must contain the application/json; version=public/v2 anything else returns 406 Not Acceptable header.

Also, the header Accept with value application/json; version=public/v2 should be in my request. The response header is always application/json.

Do you know how I can document that?

Answer 1

In OpenAPI 3.0, the request header Accept and the response header Content-Type are both defined as responses.<code>.content.<Accept value>. This needs to be defined in every operation.

paths:
  /something:
    get:
      responses:
        '200':
          description: Successful operation
          content:
            'application/json; version=public/v2':  # <-----
              schema:
                ...
         '406':
           description: Invalid media type was specified in the `Accept` header (should be `application/json; version=public/v2`)

Answer 2

In order to specify that you should perform a http request using the application/json; version=public/v2 accept header you should document it like this:

openapi: 3.0.0
info:
  version: "v2"
  title: Company App Public Api
  description: Integrate your platform with company app website

components:
  securitySchemes:
    ApiKey:
      type: 'apiKey'
      in: 'header'
      name: 'X-Access-Token'
   
  responses:
    406:
      description: "Is returned once `Accept` header has not been provided or does not contain the `application/json; version=public/v2` value."
      content:
        'application/json':
          schema:
            type: object
            properties:
              error:
                type: 'boolean'
              type:
                type: 'string'
              message:
                type: 'string'
                description: "Your access token is either missing or incorrect. Please check the X-Access-Token header and try again."
    401:
      description: "Is returned once `X-Access-Token` has not been provided"
      content:
        'application/json':
          schema:
            type: object
            properties:
              error:
                type: 'boolean'
              type:
                type: 'string'
              message:
                description: "Your access token is either missing or incorrect. Please check the X-Access-Token header and try again."
security:
  - ApiKey: []  

paths:
   /myendpoint:
     put:
       requestBody:
         required: true
         content: 
           'application/json; version=public/v2': {}
         
       responses:
         200:
            'application/json':
               #your response jhere as documented in
         406:
           $ref: '#/components/responses/406'
         401:
           $ref: '#/components/responses/401'

So with this approach you tell in the documentation that the request should be a put one with the Accept header application/json; version=public/v2 with any (or no) parameters.

Though for get requests requestBody is not a valid definition.