resuable request headers to be used in multiple request.

[AqibFayyazShaheer]

No description provided.

[AqibFayyazShaheer]

Hi, I am writing swagger documentation for my services using swaggerjsdoc and I have about 12 custom headers that will be used in 40 to 50 request each microservice and I have about 10 different microservices. with the current approach as mentioned below `

parameters:
    X-APP-TYPE:
      name: X-APP-TYPE
      in: header
      required: true
      type: string
    X-APP-VERSION:
      name: X-APP-VERSION
      in: header
      required: true
      type: string
    X-DEVICE-ID:
      name: X-DEVICE-ID
      in: header
      required: true
      type: string
    X-IP-ADDRESS:
      name: X-IP-ADDRESS
      in: header
      required: true
      type: string        
    X-CHANNEL:
      name: X-CHANNEL
      in: header
      required: true
      type: string
    X-LOB:
      name: X-LOB
      in: header
      required: true
      type: string
    Accept-Language:
      name: Accept-Language
      in: header
      required: true
      type: string
    Content-Type:
      name: Content-Type
      in: header
      required: true
      type: string
    X-TRACE-ID:
      name: X-TRACE-ID
      in: header
      required: true
      type: string
    X-LOCALE:
      name: X-LOCALE
      in: header
      required: true
      type: string
    Authorization:
      name: Authorization
      in: header
      required: true
      type: string
    TOKEN:
      name: TOKEN
      in: header
      require: true
      type: string

• /myapi:

• post:
  

•   tags:
  

•     - General
  

•   summary:  Survey
  

•   parameters:
  

•     - $ref: '#/parameters/X-APP-TYPE'
  

•     - $ref: '#/parameters/X-APP-VERSION'
  

•     - $ref: '#/parameters/X-DEVICE-ID'
  

•     - $ref: '#/parameters/X-IP-ADDRESS'
  

•     - $ref: '#/parameters/X-CHANNEL'
  

•     - $ref: '#/parameters/X-LOB'
  

•     - $ref: '#/parameters/Accept-Language'
  

•     - $ref: '#/parameters/Content-Type'
  

•     - $ref: '#/parameters/X-TRACE-ID'
  

•     - $ref: '#/parameters/X-LOCALE'
  

•     - $ref: '#/parameters/Authorization'
  

•     - $ref: '#/parameters/TOKEN'
  

I need to use $ref for each header explicitly for each request and keeping this approach I have to do this in all of my hundreds of apis which is going to cause a lot of replication and difficult to maintain.

Please help me get a better solution, thank you.

[AqibFayyazShaheer]

@handrews any suggestions please.

[handrews]

@AqibFayyazShaheer I'm not aware of anything that can improve this in OAS 3.x. This is something that OAS 4 a.k.a. Moonwalk will hopefully improve.

[DXTimer]

We are also interested in seeing an alternative approach to managing response headers, as mentioned the headers schema allows for Map[string, Header Object | Reference Object] so you are forced to introduce a lot of duplicate entries to document common headers across an OpenAPI definition.

One possible workaround I can think of for the moment is the use of YAML anchors. This, however, would require developers to render the YAML without the anchors as most tools out there would not support them, which is not the worst tradeoff one can make.

Curious to see what other people are doing to solve this?