Use openapi cli plugin to automate swagger api annotation

[nitrosx]

Summary

As highlighted by @emigun, maintenance and consistency of the swagger api documentation is expensive and prone to human error as we need to enter the same information in multiple location.

Solution

We propose to adopt the OpenAPI CLI plugin, which reduce information duplication, code cluttering and inconsistencies, and allowing complete freedom in configuration where needed.

##Additional information
Below I included an edited version of the post reported by @emigun in PR #1579

[nitrosx]

Perhaps we should consider using https://docs.nestjs.com/openapi/cli-plugin instead of annotating manually?
It is already enabled.
I have tested it a bit and it seems to work nicely.

A fairly advanced example:
Let's change

  @ApiProperty({
    type: "array",
    items: { $ref: getSchemaPath(TechniqueClass) },
    required: false,
    default: [],
    description: "Stores the metadata information for techniques.",
  })
  @IsOptional()
  @IsArray()
  @ValidateNested({ each: true })
  @Type(() => CreateTechniqueDto)
  readonly techniques?: TechniqueClass[] = [];

to (remove ApiProperty)

  @IsOptional()
  @IsArray()
  @ValidateNested({ each: true })
  @Type(() => CreateTechniqueDto)
  readonly techniques?: TechniqueClass[] = [];

That would change the openapi json from:

"techniques": {
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/TechniqueClass"
  },
  "default": [],
  "description": "Stores the metadata information for techniques."
},

to

"techniques": {
  "default": [],
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/TechniqueClass"
  }
}

As you can see everything was generated (except description, see below)

I have tried with arrays, dates and ordinary string/number and it seems to work. It also reads the ? for optional fields and correctly identifies the required ones.

We could change nest-cli.json to:

  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "plugins": [{
      "name": "@nestjs/swagger",
      "options": {
        "introspectComments": true
      }
    }]
  }
}

in order to generate the field "description" based on a comment above. Or you could still use

@ApiProperty({
    description: "This is a test description"
  })

if you prefer that. The other fields like type, items, default and others will still be generated with the plugin.

tldr; We could probably get rid of all the ApiProperty decorators and the openapi spec will automatically be generated correctly for the fields. If some doesn't work, we can still use ApiProperty on only those.

Two main benefits:

1. Less cluttered code
2. No more inconstencies (as you can see in my merge request I had to change about 20 things just for the dataset dtos)