auto generate description from comments

[qbcbyb]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://github.com/nestjs/nest/blob/master/CONTRIBUTING.md
• Tests for the changes have been added (for bug fixes / features)
  test added.
• Docs have been added / updated (for bug fixes / features)
  no docs in this project yet.

PR Type

What kind of change does this PR introduce?

[ ] Bugfix
[x] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[ ] Other... Please describe:

What is the current behavior?

When enable the plugin by modified nest-cli.json , there is no default description and example in ApiProperty and ApiOperation

What is the new behavior?

Auto generate description and (example or examples) from comment, just like this:

export abstract class Audit {
  /** test on createdAt */
  @CreateDateColumn()
  createdAt;

  // test on updatedAt1
  // test on updatedAt2
  @UpdateDateColumn()
  updatedAt;

  /**
   * test
   * version 
   * @example '0.0.1'
   * @memberof Audit
   */
  @VersionColumn()
  version;

  /**
   * testVersion
   *  
   * @example '0.0.1'
   * @example '0.0.2'
   * @memberof Audit
   */
  testVersion;
}

=>

export class Audit {
    static _OPENAPI_METADATA_FACTORY() {
        return { createdAt: { description: "test on createdAt", required: true, type: () => Object }, updatedAt: { description: "test on updatedAt1\\ntest on updatedAt2", required: true, type: () => Object }, version: { description: "test\\nversion", required: true, type: () => Object, example: "0.0.1" }, testVersion: { description: "testVersion", required: true, type: () => Object, examples: ["0.0.1", "0.0.2"] } };
    }
}

Does this PR introduce a breaking change?

[ ] Yes
[x] No

Other information

[BenWildeman]

@qbcbyb Could I make a suggestion and remove the // normal comments support. if feels wrong to use these as these aren't documentation comments. this ties in better with TS and JSDoc spec. it could potentially show a commented out line in the documentation which is obviously undesired

[kamilmysliwiec]

Thanks you for contribution. However, I'm not entirely sure why we should even extract comments to enhance the specification. These are 2 completely separate areas. I would recommend publishing this a separate plugin (separate NPM package).

[BenWildeman]

@kamilmysliwiec it would have been good to have a discussion around this instead of straight up closing it. right now in my project, we have to duplicate the comment for both swagger and JS docs, whereas, this PR would have only required one. the whole point of the swagger plugin you created was to limit the code duplication

[kamilmysliwiec]

As I've pointed out above, you can always publish a separate plugin - CLI allows applying multiple plugins at once.

[BenWildeman]

Your plugin misses the mark when you have to still use ApiProperty for specifying the description. even more so when ApiProperty originally inferred the types from TS anyway* without the plugin. but sure, more plugins it is

[qbcbyb]

@qbcbyb Could I make a suggestion and remove the // normal comments support. if feels wrong to use these as these aren't documentation comments. this ties in better with TS and JSDoc spec. it could potentially show a commented out line in the documentation which is obviously undesired

@BenWildeman, Have removed the // normal comments support. And publish in npm: @qbcbyb/nestjs_swagger_plugin

[sjakos]

@kamilmysliwiec is this PR lined up to be merged in soon?

[kamilmysliwiec]

Thanks for your contribution!