Introspected comment on controller class makes top-level comment the operation description then overrides it with TsDoc "remarks" directive

[calebpitan]

Is there an existing issue for this?

• I have searched the existing issues

Current behavior

When using the introspect comment on a controller class the remarks directive overrides the top-level comment as the description key.

Another weird thing is that my editor doesn't provide the remarks directive in the autosuggest but does for the summary directive, so I think the "standard" summary directive would be the most intuitive.

Minimum reproduction code

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

Lines 236 to 246 in 979f256

	const hasRemarksKey = hasPropertyKey(
	'description',
	factory.createNodeArray(apiOperationExistingProps)
	);
	if (!hasRemarksKey && tags.remarks) {
	const remarksPropertyAssignment = factory.createPropertyAssignment(
	'description',
	createLiteralFromAnyValue(factory, tags.remarks)
	);
	properties.push(remarksPropertyAssignment);
	}

Steps to reproduce

A source like this:

  /**
   * Some comment to be used as operation description
   *
   * @remarks Some remarks to be used as operation summary
   */
  @ApiResponse({ status: 200, description: 'Administrator Retrieved' })
  @ApiOAuth2(['super'])
  @RequireAuth()
  @Get(':id')
  async getAdministratorById() {}

Generates an output like this

__decorate([
    openapi.ApiOperation({ description: "Some comment to be used as operation description", description: "Some remarks to be used as operation summary" }),
    ...
])

Expected behavior

The tsdoc remarks and/or summary directive should not override the operation description instead be used as the operation summary

Package version

7.3.1

NestJS version

10.3.7

Node.js version

20, 21

In which operating systems have you tested?

• macOS
• Windows
• Linux

Other

No response

[djalilhebal]

I have a similar issue.

It is not clear how the swagger plugin is handling JSDoc comments.

Case 1: It includes only the @remarks section. This is unexpected.

  /**
   * This should be the summary according to TSDoc
   * 
   * @remarks
   * 
   * This should be a detailed description according to TSDoc
   * 
   * @privateRemarks
   * 
   * This should be a detailed description according to TSDoc,
   * but it must not be included in the output (`.d.ts` or OpenAPI spec or whatever).
   * 
   * @summary This should be a summary according to JSDoc.
   */
  @Get()
  async findAll(@Query() paginationParams: PaginationQueryDto): Promise<Product[]> {
    return this.productsService.findAll(paginationParams);
  }

API JSON:

    "/products": {
      "get": {
        "operationId": "ProductsController_findAll",
        "summary": "",
        "description": "This should be a detailed description according to TSDoc",
        "parameters": [
// ...

Case 2: It does not respect @summary. This is unexpected.

  /**
   * This should be the summary according to TSDoc
   * 
   * @summary This should be a summary according to JSDoc.
   */
  @Get()
  async findAll(@Query() paginationParams: PaginationQueryDto): Promise<Product[]> {
    return this.productsService.findAll(paginationParams);
  }

API JSON:

    "/products": {
      "get": {
        "operationId": "ProductsController_findAll",
        "summary": "",
        "description": "This should be the summary according to TSDoc\n\n@summary This should be a summary according to JSDoc.",
        "parameters": [
// ...

Case 3: @privateRemarks are not included. This is works as expected.

API JSON:

    "/products": {
      "get": {
        "operationId": "ProductsController_findAll",
        "summary": "",
        "description": "This should be the summary according to TSDoc, but a detail description according to JSDoc.",
        "parameters": [
// ...

References

• JSDoc https://jsdoc.app/tags-summary

• TSDoc https://tsdoc.org/pages/tags/remarks/