Enhance introspectComments to provide summary and description for routes

[tom-thorne]

I'm submitting a...

[ ] Regression 
[ ] Bug report
[x] Feature request
[ ] Documentation issue or request
[ ] Support request => Please do not submit support request here, instead post your question on Stack Overflow.

Current behavior

The nest-cli swagger plugin with introspectComments set to true works very nicely adding descriptions to routes from comments.

However, it is not yet possible to add a summary or a title to a route via a comment. Instead you have to revert to adding a decorator again which is a shame, as below.

    /**
     * Gets operations. Use blah blah blah to filter the operation types in the response.
     */
    @Get()
    @ApiOperation({ summary: 'Get All Operations' })
    async getOperations( @Context() context: INestContext, @Query() params: GetOperationsQuery ): Promise<GetOperationsResponse> {

Desired behavior

What would be nice if the comment's 1st line could represent the summary/title, and subsequent lines the description, as below. This removes the need for the @ApiOperation decorator.

    /**
     * Get an operation by Id
     * Gets operations. Use blah blah blah to filter the operation types in the response.
     */
    @Get()
    async getOperations( @Context() context: INestContext, @Query() params: GetOperationsQuery ): Promise<GetOperationsResponse> {

Environment

Nest version: 7.5.1
@nestjs/swagger: 4.7.6

[kamilmysliwiec]

Would you like to create a PR for this issue?

[tom-thorne]

I can have a go - are there any docs, or please could you give me a hint as to what function to look at?

[kamilmysliwiec]

That's the method you would have to modify: https://github.com/nestjs/swagger/blob/master/lib/plugin/visitors/controller-class.visitor.ts#L88 (after extractedComments if condition)

[tom-thorne]

Thanks - and are there any unit tests I can leverage?

[petrzjunior]

I would be too interested in supporting better instrospection. I usually write my comment in a TSDoc format with leading asterisks on each line, which are sadly not stripped.

/**
 * Public description, visible to customers.
 * @example
 * Summer Party
 */

Most robust solution could involve the official TSDoc parser (you can view the AST in their playground), but it seems to parse the comments down to paragraphs and newlines, the AST is far too fine grained.
The OpenAPI on the other hand supports CommonMark content, so we should probably not parse the comment and reconstruct back into Markdown.

I would be happy to contribute, but I'm not sure, how to tackle particular problem.

[kamilmysliwiec]

Let's track this here #1207

[emretepedev]

However, it is not yet possible to add a summary or a title to a route via a comment. Instead you have to revert to adding a decorator again which is a shame, as below.

Is there any update on this?