Open MIrinkov opened 7 months ago
Update the api operation explorer to also set the description key on operation metadata
Would you like to create a PR for this issue?
I can try. Depending on how easy it is to set up this project locally, I may succeed soon.
A quick update. I've started work on this, and while adding a single line of code is easy enough, I'm still figuring out how to update the tests. I'll update this thread when I've got something to show.
Is there an existing issue for this?
Current behavior
https://github.com/nestjs/swagger/blob/ed528d44d416f78a8159995de31b9d4df6024762/lib/explorers/api-operation.explorer.ts#L29-L45
When using Swagger CLI Plugin, when using
introspectComments
feature, it will put the JSDoc comment found on the API Operation (i.e. on the controller method) intoApiOperation
decorator metadata.The issue is that by default, the plugin will populate the
description
key (i.e. the default value for plugin optioncontrollerKeyOfComment
is"description"
). However, if you look at theapi-operation-explorer.ts
file, you will see that when applying this metadata to the controller method we only doconst { summary, deprecated, tags } = metadata[key];
. In other words, with default plugin configuration the API Operation comment introspection actually doesn't work!After spending a few hours on this and understanding the underlying issue, the obvious workaround is to update nest-cli.json file by setting
"controllerKeyOfComment": "summary"
.Minimum reproduction code
I hope the link to the "faulty" code is enough
Steps to reproduce
No response
Expected behavior
According to the docs (https://docs.nestjs.com/openapi/cli-plugin#comments-introspection)
So I would expect the behavior to match the docs. Some ways to achieve that:
description
key on operation metadatacontrollerKeyOfComment
plugin setting to be'summary'
and also update the docs accordinglyPackage version
7.1.17
NestJS version
10.3.0
Node.js version
v18.17.1
In which operating systems have you tested?
Other
The default options for the plugin are declared here. This is where the default value of
description
is coming from. https://github.com/nestjs/swagger/blob/ed528d44d416f78a8159995de31b9d4df6024762/lib/plugin/merge-options.ts#L16-L25And this is where it's being read. https://github.com/nestjs/swagger/blob/ed528d44d416f78a8159995de31b9d4df6024762/lib/plugin/visitors/controller-class.visitor.ts#L202
After that it gets put into metadata, and eventually the
api-operation-explorer
code will fail to read the description, expecting to get the summary instead. https://github.com/nestjs/swagger/blob/ed528d44d416f78a8159995de31b9d4df6024762/lib/explorers/api-operation.explorer.ts#L29-L45