How to add definitions for headers?

[Flupster]

I can't seem to find anything in the source/examples with defining a response header

Is this a feature not yet available or have I missed the relevant examples?

[kevinccbsg]

Hi @Flupster,

Yes, I think this is not ready yet in express-jsdoc-swagger for responses. We will consider adding that in the next release as a new feature. How would you like to create the comments to provide response headers? We will keep this issue updated with the decision we will make to create these response headers.

In the meantime, you can still use express-jsdoc-swagger by using the merge option. As you can see on our Docs page you can extend your response headers JSON with the documentation generated by the JSDOC comments. I hope that helps you while we work on this new feature 👍

[Flupster]

Maybe something like

/**
 * GET /api/v1/albums
 * @summary This is the summary or description of the endpoint
 * @tags album
 * @return {array<Song>} 200 - success response - application/json
 * @return {string} header - x-my-header - description of my header
 * @return {number} header - x-load-time - Time in milliseconds it took to generate body
 */

Just off the top of my head

I didn't look into sources of express-jsdoc-swagger but perhaps if the @return response code from jsdoc isn't a number then it's a custom option?

Benefits of this is you can define the headers type like

@return {Date} header - x-expires - Time until cache is stale and new data can be retrieved

The reason I wrote this issue is I didn't want to expose the created_at/updated_at in the returned body and instead opted to use x-created-at and x-updated-at headers

So my personal usage would be something like:

/**
 * GET /api/characters/{character_id}/
 * @summary Character by id
 * @tags Characters
 * @param {number} character_id.path - ID of the Character
 * @return {Character} 200 - success response - application/json
 * @return {Date} header - x-created-at - Date the character was found
 * @return {Date} header - x-updated-at - Date the last time the character was updated
 */

[Flupster]

Thinking about it some more, a request can only respond with headers and body, nothing more nothing less.

So an alternative option would be

/**
 * GET /api/characters/{character_id}/
 * @summary Character by id
 * @tags Characters
 * @param {number} character_id.path - ID of the Character
 * @return {Character} 200 - success response - application/json
 * @return {Date}  x-created-at - Date the character was found
 * @return {Date}  x-updated-at - Date the last time the character was updated
 */

If the "status code" isn't a number then auto recognise it as a header option and the "status code" would be the headers key

[kevinccbsg]

Hi @Flupster

II really like this idea 🎉 and I was working on that.

/**
 * GET /api/characters/{character_id}/
 * @summary Character by id
 * @tags Characters
 * @param {number} character_id.path - ID of the Character
 * @return {Character} 200 - success response - application/json
 * @return {Date}  x-created-at - Date the character was found
 * @return {Date}  x-updated-at - Date the last time the character was updated
 */

If the "status code" isn't a number then auto recognise it as a header option and the "status code" would be the headers key

However, there is a problem that each header is part of a response (Response Headers section). Then, we have to figure out which response (200, 3x, 4x or 5x) has those headers 🤔 I'm still thinking about a proper way to define that. I think this one could be the best one, as we could specify where this header belongs.

* @return {string} 200 - header description - header - x-created-at

[kevinccbsg]

We are going to upload updates about this in this branch