refactor(proposal): use openapi plugin (#1629)

* use openapi plugin for proposal module
SciCatProject · Jan 22, 2025 · adaacd0 · adaacd0
1 parent c5fbc45
commit adaacd0
Show file tree

Hide file tree

Showing 6 changed files with 127 additions and 217 deletions.
diff --git a/nest-cli.json b/nest-cli.json
@@ -5,7 +5,12 @@
     "plugins": [{
       "name": "@nestjs/swagger",
       "options": {
-        "dtoFileNameSuffix": [".dto.ts", "sample.schema.ts"],
+        "dtoFileNameSuffix": [
+          ".dto.ts",
+          "sample.schema.ts",
+          "proposal.schema.ts",
+          "measurement-period.schema.ts"
+        ],
         "introspectComments": true
       }
     }]

diff --git a/src/proposals/dto/create-measurement-period.dto.ts b/src/proposals/dto/create-measurement-period.dto.ts
@@ -1,37 +1,27 @@
-import { ApiProperty } from "@nestjs/swagger";
 import { IsDateString, IsOptional, IsString } from "class-validator";
 
 export class CreateMeasurementPeriodDto {
-  @ApiProperty({
-    type: String,
-    required: true,
-    description:
-      "Instrument or beamline identifier where measurement was pursued, e.g. /PSI/SLS/TOMCAT",
-  })
+  /**
+   * Instrument or beamline identifier where measurement was pursued, e.g. /PSI/SLS/TOMCAT
+   */
   @IsString()
   readonly instrument: string;
 
-  @ApiProperty({
-    type: Date,
-    description:
-      "Time when measurement period started, format according to chapter 5.6 internet date/time format in RFC 3339. Local times without timezone/offset info are automatically transformed to UTC using the timezone of the API server.",
-  })
+  /**
+   * Time when measurement period started, format according to chapter 5.6 internet date/time format in RFC 3339. Local times without timezone/offset info are automatically transformed to UTC using the timezone of the API server.
+   */
   @IsDateString()
   readonly start: Date;
 
-  @ApiProperty({
-    type: Date,
-    description:
-      "Time when measurement period ended, format according to chapter 5.6 internet date/time format in RFC 3339. Local times without timezone/offset info are automatically transformed to UTC using the timezone of the API server.",
-  })
+  /**
+   * Time when measurement period ended, format according to chapter 5.6 internet date/time format in RFC 3339. Local times without timezone/offset info are automatically transformed to UTC using the timezone of the API server.
+   */
   @IsDateString()
   readonly end: Date;
 
-  @ApiProperty({
-    type: String,
-    description:
-      "Additional information relevant for this measurement period, e.g. if different accounts were used for data taking.",
-  })
+  /**
+   * Additional information relevant for this measurement period, e.g. if different accounts were used for data taking.
+   */
   @IsOptional()
   @IsString()
   readonly comment?: string;

diff --git a/src/proposals/dto/create-proposal.dto.ts b/src/proposals/dto/create-proposal.dto.ts
@@ -1,14 +1,10 @@
-import { ApiProperty } from "@nestjs/swagger";
 import { IsString } from "class-validator";
 import { UpdateProposalDto } from "./update-proposal.dto";
 
 export class CreateProposalDto extends UpdateProposalDto {
-  @ApiProperty({
-    type: String,
-    required: true,
-    description:
-      "Globally unique identifier of a proposal, eg. PID-prefix/internal-proposal-number. PID prefix is auto prepended.",
-  })
+  /**
+   * Globally unique identifier of a proposal, eg. PID-prefix/internal-proposal-number. PID prefix is auto prepended.
+   */
   @IsString()
   readonly proposalId: string;
 }
diff --git a/src/proposals/dto/update-proposal.dto.ts b/src/proposals/dto/update-proposal.dto.ts
@@ -1,4 +1,4 @@
-import { ApiProperty, ApiTags, PartialType } from "@nestjs/swagger";
+import { ApiTags, PartialType } from "@nestjs/swagger";
 import { Type } from "class-transformer";
 import {
   IsArray,
@@ -14,132 +14,100 @@ import { CreateMeasurementPeriodDto } from "./create-measurement-period.dto";
 
 @ApiTags("proposals")
 export class UpdateProposalDto extends OwnableDto {
-  @ApiProperty({
-    type: String,
-    required: false,
-    description: "Email of principal investigator.",
-  })
+  /**
+   * Email of principal investigator.
+   */
   @IsOptional()
   @IsEmail()
   readonly pi_email?: string;
 
-  @ApiProperty({
-    type: String,
-    required: false,
-    description: "First name of principal investigator.",
-  })
+  /**
+   * First name of principal investigator.
+   */
   @IsOptional()
   @IsString()
   readonly pi_firstname?: string;
 
-  @ApiProperty({
-    type: String,
-    required: false,
-    description: "Last name of principal investigator.",
-  })
+  /**
+   * Last name of principal investigator.
+   */
   @IsOptional()
   @IsString()
   readonly pi_lastname?: string;
 
-  @ApiProperty({
-    type: String,
-    required: true,
-    description: "Email of main proposer.",
-  })
+  /**
+   * Email of main proposer.
+   */
   @IsEmail()
   readonly email: string;
 
-  @ApiProperty({
-    type: String,
-    required: false,
-    description: "First name of main proposer.",
-  })
+  /**
+   * First name of main proposer.
+   */
   @IsOptional()
   @IsString()
   readonly firstname?: string;
 
-  @ApiProperty({
-    type: String,
-    required: false,
-    description: "Last name of main proposer.",
-  })
+  /**
+   * Last name of main proposer.
+   */
   @IsOptional()
   @IsString()
   readonly lastname?: string;
 
-  @ApiProperty({
-    type: String,
-    required: true,
-    description: "The title of the proposal.",
-  })
+  /**
+   * The title of the proposal.
+   */
   @IsString()
   readonly title: string;
 
-  @ApiProperty({
-    type: String,
-    required: false,
-    description: "The proposal abstract.",
-  })
+  /**
+   * The proposal abstract.
+   */
   @IsOptional()
   @IsString()
   readonly abstract?: string;
 
-  @ApiProperty({
-    type: Date,
-    required: false,
-    description: "The date when the data collection starts.",
-  })
+  /**
+   * The date when the data collection starts.
+   */
   @IsOptional()
   @IsDateString()
   readonly startTime?: Date;
 
-  @ApiProperty({
-    type: Date,
-    required: false,
-    description: "The date when data collection finishes.",
-  })
+  /**
+   * The date when data collection finishes.
+   */
   @IsOptional()
   @IsDateString()
   readonly endTime?: Date;
 
-  @ApiProperty({
-    type: CreateMeasurementPeriodDto,
-    isArray: true,
-    required: false,
-    description:
-      "Embedded information used inside proposals to define which type of experiment has to be pursued, where (at which instrument) and when.",
-  })
+  /**
+   * Embedded information used inside proposals to define which type of experiment has to be pursued, where (at which instrument) and when.
+   */
   @IsArray()
   @IsOptional()
   @ValidateNested({ each: true })
   @Type(() => CreateMeasurementPeriodDto)
   readonly MeasurementPeriodList?: CreateMeasurementPeriodDto[];
 
-  @ApiProperty({
-    type: Object,
-    required: false,
-    default: {},
-    description: "JSON object containing the proposal metadata.",
-  })
+  /**
+   * JSON object containing the proposal metadata.
+   */
   @IsOptional()
   @IsObject()
-  readonly metadata?: Record<string, unknown>;
+  readonly metadata?: Record<string, unknown> = {};
 
-  @ApiProperty({
-    type: String,
-    required: false,
-    description: "Parent proposal id.",
-  })
+  /**
+   * Parent proposal id.
+   */
   @IsOptional()
   @IsString()
   readonly parentProposalId?: string;
 
-  @ApiProperty({
-    type: String,
-    required: false,
-    description:
-      "Characterize type of proposal, use some of the configured values",
-  })
+  /**
+   * Characterize type of proposal, use some of the configured values
+   */
   @IsOptional()
   @IsString()
   readonly type?: string;

diff --git a/src/proposals/schemas/measurement-period.schema.ts b/src/proposals/schemas/measurement-period.schema.ts
@@ -1,42 +1,32 @@
 import { Prop, Schema, SchemaFactory } from "@nestjs/mongoose";
-import { ApiProperty } from "@nestjs/swagger";
 import { Document } from "mongoose";
 import { QueryableClass } from "src/common/schemas/queryable.schema";
 
 export type MeasurementPeriodDocument = MeasurementPeriodClass & Document;
 
 @Schema()
 export class MeasurementPeriodClass extends QueryableClass {
-  @ApiProperty({
-    type: String,
-    required: true,
-    description:
-      "Instrument or beamline identifier where measurement was pursued, e.g. /PSI/SLS/TOMCAT",
-  })
+  /**
+   * Instrument or beamline identifier where measurement was pursued, e.g. /PSI/SLS/TOMCAT
+   */
   @Prop({ type: String, required: true, index: true })
   instrument: string;
 
-  @ApiProperty({
-    type: Date,
-    description:
-      "Time when measurement period started, format according to chapter 5.6 internet date/time format in RFC 3339. Local times without timezone/offset info are automatically transformed to UTC using the timezone of the API server.",
-  })
+  /**
+   * Time when measurement period started, format according to chapter 5.6 internet date/time format in RFC 3339. Local times without timezone/offset info are automatically transformed to UTC using the timezone of the API server.
+   */
   @Prop({ type: Date, index: true })
   start: Date;
 
-  @ApiProperty({
-    type: Date,
-    description:
-      "Time when measurement period ended, format according to chapter 5.6 internet date/time format in RFC 3339. Local times without timezone/offset info are automatically transformed to UTC using the timezone of the API server.",
-  })
+  /**
+   * Time when measurement period ended, format according to chapter 5.6 internet date/time format in RFC 3339. Local times without timezone/offset info are automatically transformed to UTC using the timezone of the API server.
+   */
   @Prop({ type: Date, index: true })
   end: Date;
 
-  @ApiProperty({
-    type: String,
-    description:
-      "Additional information relevant for this measurement period, e.g. if different accounts were used for data taking.",
-  })
+  /**
+   * Additional information relevant for this measurement period, e.g. if different accounts were used for data taking.
+   */
   @Prop({ type: String })
   comment: string;
 }