Swagger Build Issue with @TypedHeaders(): Incorrect Header Object Representation

[de-novo]

Problem

When using @TypedHeaders(), Swagger parameters for headers are written as an object in the generated documentation.

However, when executing requests within Swagger UI, the server outputs the headers in the following format:

type IHeader = {
    'x-custom': string
}

// headers {
//     headers: IHeader
// }

This results in the headers being encapsulated within an additional headers object, which is not the intended structure.

Postman and frontend applications work correctly with the headers without this encapsulation.

Suspected Issue

Upon inspecting the generated Swagger file, I found that it's structured as follows:

"path": {
    "/": {
        "[method]": {
            //...
            "parameters": [
                {
                    "name": "headers",
                    "in": "header",
                    "schema": {
                        "$ref": "#/components/schemas/IHeader"
                    },
                    "description": "",
                    "required": true
                }
            ]
            //...
        }
    }
},
//...
"components": {
    "schemas": {
        "IHeader": {
            "type": "object",
            "properties": {
                "X-Custom": {
                    "type": "string",
                    "description": "custom type"
                }
            },
            "nullable": false
        }
    }
},

This indicates that the headers parameter is referencing an IHeader schema, which is defined as an object with properties such as X-Custom.

Solution for Resolution

To resolve this issue, the parameters must be defined in the following format instead:

"parameters": [
    {
        "name": "X-Custom",
        "in": "header",
                 "schema": {
                       "type": "string"
                  },
        "description": "",
        "required": true
    }
],

By defining each header field individually in the parameters section, without using $ref to refer to a schema object, we can ensure the correct structure and handling of header parameters in Swagger UI. This approach aligns with the Swagger/OpenAPI specification and ensures compatibility with tools that generate or interpret Swagger documentation.

[de-novo]

Additionally, after writing the code as follows:

export interface IHeader {
  /**
   * Custom
   */
  'X-Custom'?: string;
  headers: string;
}

When outputting, it results in { 'X-Custom': undefined, headers: "X-Custom,'test'" }.

[samchon]

https://nestia.io/docs/sdk/swagger/#configuration

Configure swagger.decompose property to be true in the nestia.config.ts file

[de-novo]

I am very pleased to learn that setting Nestia's swagger.decompose property to true was an effective solution. I appreciate the prompt response and support. I hope that Nestia becomes even more well-known and widely used by many developers. Thank you!

[samchon]

I think I should enhance the decompose option in the documents.