OAS3: Why is Accept header defined in Response?

758 views Asked by At

It says here that one should not define the Accept header inside a OAS3 Yaml file as a parameter but in responses.<code>.content.<media-type>. Example:

paths:
  /employees:
    get:
      summary: Returns a list of employees.
      responses:
        '200':      # Response
          description: OK
          content:  # Response body
            application/json:  # Media type
              schema:          # Must-have
                type: object   # Data type
                properties: 
                  id:
                    type: integer
                  name:
                    type: string
                  fullTime: 
                    type: boolean
                example:       # Sample data
                    id: 1
                    name: Jessica Right
                    fullTime: true

This makes me wonder because if I create a client based on that OAS3 file using swagger-codegen the string mentioned below "content:" (in my example application/json) gets used as is as Accept header when making the /employees call using that client. Thus the folling piece of code, which identifies the individual who is making use of my API ("userID"), would not have any effect:

DefaultApi api = new DefaultApi();
api.getApiClient().addDefaultHeader("Accept", "application/vnd.mycompany.userID.v1+json");

But as the owner of my API I don't want to provide a swagger file for each user.

Why does the Accept header in OAS3 get defined in the response section which in my opinion should only define the media type of the result?

0

There are 0 answers