CLI Plugin with comment introspection does not set ApiOperation description

[MIrinkov]

Is there an existing issue for this?

• I have searched the existing issues

Current behavior

swagger/lib/explorers/api-operation.explorer.ts

Lines 29 to 45 in ed528d4

	methodKeys.forEach((key) => {
	const operationMeta = {};
	const { summary, deprecated, tags } = metadata[key];
	applyIfNotNil(operationMeta, 'summary', summary);
	applyIfNotNil(operationMeta, 'deprecated', deprecated);
	applyIfNotNil(operationMeta, 'tags', tags);
	if (Object.keys(operationMeta).length === 0) {
	return;
	}
	ApiOperation(operationMeta, { overrideExisting: false })(
	classPrototype,
	key,
	Object.getOwnPropertyDescriptor(classPrototype, key)
	);
	});

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) into ApiOperation decorator metadata.

The issue is that by default, the plugin will populate the description key (i.e. the default value for plugin option controllerKeyOfComment is "description"). However, if you look at the api-operation-explorer.ts file, you will see that when applying this metadata to the controller method we only do const { 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)

By default, these options are set to "description". This means the plugin will assign "Create some resource" to description key on the ApiOperation operator.

So I would expect the behavior to match the docs. Some ways to achieve that:

• Update the api operation explorer to also set the description key on operation metadata
• Update the default value for controllerKeyOfComment plugin setting to be 'summary' and also update the docs accordingly
• Maybe some other combination of the two or something else entirely

Package version

7.1.17

NestJS version

10.3.0

Node.js version

v18.17.1

In which operating systems have you tested?

• macOS
• Windows
• Linux

Other

The default options for the plugin are declared here. This is where the default value of description is coming from.

swagger/lib/plugin/merge-options.ts

Lines 16 to 25 in ed528d4

	const defaultOptions: PluginOptions = {
	dtoFileNameSuffix: ['.dto.ts', '.entity.ts'],
	controllerFileNameSuffix: ['.controller.ts'],
	classValidatorShim: true,
	dtoKeyOfComment: 'description',
	controllerKeyOfComment: 'description',
	introspectComments: false,
	readonly: false,
	debug: false
	};

And this is where it's being read.

swagger/lib/plugin/visitors/controller-class.visitor.ts

Line 202 in ed528d4

const keyToGenerate = options.controllerKeyOfComment;

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.

swagger/lib/explorers/api-operation.explorer.ts

Lines 29 to 45 in ed528d4

	methodKeys.forEach((key) => {
	const operationMeta = {};
	const { summary, deprecated, tags } = metadata[key];
	applyIfNotNil(operationMeta, 'summary', summary);
	applyIfNotNil(operationMeta, 'deprecated', deprecated);
	applyIfNotNil(operationMeta, 'tags', tags);
	if (Object.keys(operationMeta).length === 0) {
	return;
	}
	ApiOperation(operationMeta, { overrideExisting: false })(
	classPrototype,
	key,
	Object.getOwnPropertyDescriptor(classPrototype, key)
	);
	});

[kamilmysliwiec]

Update the api operation explorer to also set the description key on operation metadata

Would you like to create a PR for this issue?

[MIrinkov]

I can try. Depending on how easy it is to set up this project locally, I may succeed soon.

[MIrinkov]

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.