Surnet/swagger-jsdoc

Display custom headers in resuable way (Components/parameters) with different field for each header in swagger ui express

Opened this issue · 7 comments

AqibFayyazShaheer commented

Hi, I have about 12 different headers and all those are needed in about 40 to 50 different request so obviously I am looking for some reusable way and I want to $ref all the headers at once instead of use $ref for all the headers one by one in parameters part and it works as well using below code example

components:
  parameters:
    CustomHeaders:
      name: headers
      in: header
      description: Custom headers
      schema:
        type: object
        properties:
          X-API-Key:
            type: string
            description: API key for authentication
          Authorization:
            type: string
            description: Bearer token for authorization

paths:
  /example:
    get:
      summary: Get example data
      parameters:
        - $ref: '#/components/parameters/CustomHeaders'

The only Issue is it creates only one object for entering all the headers instead of separate fields for all the headers in ui. Any help would be greatly appreciated.
@daniloab

daniloab commented

I do not have sure if I get the entire idea here. Can you provide a repo as an example to make things clear?

AqibFayyazShaheer commented

I mean it creates one object for all the headers for entering the values instead of separate filed for individual header as show in fig
image

AqibFayyazShaheer commented

I want to have X-API-key as seperate string value and Authorization as seperate value as shown in fig
image
for the above solution I have to use parameters:

  • $ref: '#/components/parameters/X-API-key
  • $ref: '#/components/parameters/Authorizatoin

but what I want is to use like this

  • $ref: '#/components/parameters/
    so I dont have to ref all the 11 header everytime instead just once in every request.
AqibFayyazShaheer commented

It would be great If you can provide some way around, I have been messing my head around it for many days but could not find any better way.

daniloab commented

May I believe this is related to openapi specification. Can you try this?

  • 👍1
AqibFayyazShaheer commented

openapi: 3.0.1 info: title: API version: 1.0.0 paths: /: get: responses: '200': description: Successful Request content: application/json: schema: type: array items: $ref: '#/components/schemas/User' headers: 'X-Total-Items': $ref: '#/components/headers/xTotalItems' 'X-Total-Pages': $ref: '#/components/headers/xTotalPages' components: schemas: User: {} headers: xTotalItems: schema: type: integer description: test xTotalPages: schema: type: integer description: test

ok lets take above example shared in link you mentioned so only thing I want is instead of referring each header one by one like this

      headers:
        'X-Total-Items':
           $ref: '#/components/headers/xTotalItems'
        'X-Total-Pages':
           $ref: '#/components/headers/xTotalPages'

can I reference all the header at once like
headers:
$ref: '#/components/headers'

I want to do this because I have about 11 headers and all those will be used in about 50 different request so it will cause a lot of repetition for me.

daniloab commented

openapi: 3.0.1 info: title: API version: 1.0.0 paths: /: get: responses: '200': description: Successful Request content: application/json: schema: type: array items: $ref: '#/components/schemas/User' headers: 'X-Total-Items': $ref: '#/components/headers/xTotalItems' 'X-Total-Pages': $ref: '#/components/headers/xTotalPages' components: schemas: User: {} headers: xTotalItems: schema: type: integer description: test xTotalPages: schema: type: integer description: test

ok lets take above example shared in link you mentioned so only thing I want is instead of referring each header one by one like this

      headers:
        'X-Total-Items':
           $ref: '#/components/headers/xTotalItems'
        'X-Total-Pages':
           $ref: '#/components/headers/xTotalPages'

can I reference all the header at once like headers: $ref: '#/components/headers'

I want to do this because I have about 11 headers and all those will be used in about 50 different request so it will cause a lot of repetition for me.

the swagger-jsdocs will help you to build your yml file to your swagger api. What you want to do is related to Openapi specification. Looks like you need to refer each header in your requests