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

calebpitan commented 7 months ago

Is there an existing issue for this?

[X] 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

https://github.com/nestjs/swagger/blob/979f25694209ec677cb079bd95037bbe648d2bcc/lib/plugin/visitors/controller-class.visitor.ts#L236-L246

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?

[X] macOS
[ ] Windows
[X] Linux

Other

No response

djalilhebal commented 6 months ago

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/

kamilmysliwiec commented 1 month ago

https://github.com/nestjs/swagger/commit/1535566af68c45ea88306a305ecd1f995c4cae8a

nestjs / swagger