Merge pull request #766 from hedgedoc/feat/dto-docs

nest-cli.json

@@ -2,6 +2,13 @@
   "collection": "@nestjs/schematics",
   "sourceRoot": "src",
   "compilerOptions": {
-    "plugins": ["@nestjs/swagger/plugin"]
+    "plugins": [
+      {
+        "name": "@nestjs/swagger",
+        "options": {
+          "introspectComments": true
+        }
+      }
+    ]
   }
 }

src/history/history-entry-update.dto.ts

@@ -7,6 +7,9 @@
 import { IsBoolean } from 'class-validator';
 
 export class HistoryEntryUpdateDto {
+  /**
+   * True if the note should be pinned
+   */
   @IsBoolean()
   pinStatus: boolean;
 }

src/history/history-entry.dto.ts

@@ -8,8 +8,16 @@ import { IsBoolean, ValidateNested } from 'class-validator';
 import { NoteMetadataDto } from '../notes/note-metadata.dto';
 
 export class HistoryEntryDto {
+  /**
+   * Metadata of this note
+   */
   @ValidateNested()
   metadata: NoteMetadataDto;
+
+  /**
+   * True if this note is pinned
+   * @example false
+   */
   @IsBoolean()
   pinStatus: boolean;
 }

src/notes/note-authorship.dto.ts

@@ -8,16 +8,41 @@ import { IsDate, IsNumber, IsString, Min } from 'class-validator';
 import { UserInfoDto } from '../users/user-info.dto';
 
 export class NoteAuthorshipDto {
+  /**
+   * Username of the user who authored this section
+   * @example "john.smith"
+   */
   @IsString()
   userName: UserInfoDto['userName'];
+
+  /**
+   * Character index of the start of this section
+   * @example 102
+   */
   @IsNumber()
   @Min(0)
   startPos: number;
+
+  /**
+   * Character index of the end of this section
+   * Must be greater than {@link startPos}
+   * @example 154
+   */
   @IsNumber()
   @Min(0)
   endPos: number;
+
+  /**
+   * Datestring of the time this section was created
+   * @example "2020-12-01 12:23:34"
+   */
   @IsDate()
   createdAt: Date;
+
+  /**
+   * Datestring of the last time this section was edited
+   * @example "2020-12-01 12:23:34"
+   */
   @IsDate()
   updatedAt: Date;
 }

src/notes/note-metadata.dto.ts

@@ -8,6 +8,7 @@ import {
   IsArray,
   IsDate,
   IsNumber,
+  IsOptional,
   IsString,
   ValidateNested,
 } from 'class-validator';
@@ -15,37 +16,107 @@ import { UserInfoDto } from '../users/user-info.dto';
 import { NotePermissionsDto } from './note-permissions.dto';
 
 export class NoteMetadataDto {
+  /**
+   * ID of the note
+   */
   @IsString()
   id: string;
+
+  /**
+   * Alias of the note
+   * Can be null
+   */
   @IsString()
+  @IsOptional()
   alias: string;
+
+  /**
+   * Title of the note
+   * Does not contain any markup but might be empty
+   * @example "Shopping List"
+   */
   @IsString()
   title: string;
+
+  /**
+   * Description of the note
+   * Does not contain any markup but might be empty
+   * @example Everything I want to buy
+   */
   @IsString()
   description: string;
+
+  /**
+   * List of tags assigned to this note
+   * @example "['shopping', 'personal']
+   */
   @IsArray()
   @IsString({ each: true })
   tags: string[];
+
+  /**
+   * Datestring of the last time this note was updated
+   * @example "2020-12-01 12:23:34"
+   */
   @IsDate()
   updateTime: Date;
+
+  /**
+   * User that last edited the note
+   */
   @ValidateNested()
   updateUser: UserInfoDto;
+
+  /**
+   * Counts how many times the published note has been viewed
+   * @example 42
+   */
   @IsNumber()
   viewCount: number;
+
+  /**
+   * Datestring of the time this note was created
+   * @example "2020-12-01 12:23:34"
+   */
   @IsDate()
   createTime: Date;
+
+  /**
+   * List of usernames that edited the note
+   * @example "['john.smith', 'jane.smith']"
+   */
   @IsArray()
   @ValidateNested()
   editedBy: UserInfoDto['userName'][];
+
+  /**
+   * Permissions currently in effect for the note
+   */
   @ValidateNested()
   permissions: NotePermissionsDto;
 }
 
 export class NoteMetadataUpdateDto {
+  /**
+   * New title of the note
+   * Can not contain any markup and might be empty
+   * @example "Shopping List"
+   */
   @IsString()
   title: string;
+
+  /**
+   * New description of the note
+   * Can not contain any markup but might be empty
+   * @example Everything I want to buy
+   */
   @IsString()
   description: string;
+
+  /**
+   * New list of tags assigned to this note
+   * @example "['shopping', 'personal']
+   */
   @IsArray()
   @IsString({ each: true })
   tags: string[];

src/notes/note-permissions.dto.ts

@@ -8,57 +8,124 @@ import { IsArray, IsBoolean, IsString, ValidateNested } from 'class-validator';
 import { UserInfoDto } from '../users/user-info.dto';
 
 export class NoteUserPermissionEntryDto {
+  /**
+   * User this permission applies to
+   */
   @ValidateNested()
   user: UserInfoDto;
+
+  /**
+   * True if the user is allowed to edit the note
+   * @example false
+   */
   @IsBoolean()
   canEdit: boolean;
 }
 
 export class NoteUserPermissionUpdateDto {
+  /**
+   * Username of the user this permission should apply to
+   * @example "john.smith"
+   */
   @IsString()
   username: string;
+
+  /**
+   * True if the user should be allowed to edit the note
+   * @example false
+   */
   @IsBoolean()
   canEdit: boolean;
 }
 
 export class GroupInfoDto {
+  /**
+   * Name of the group
+   * @example "superheroes"
+   */
   @IsString()
   name: string;
+
+  /**
+   * Display name of this group
+   * @example "Superheroes"
+   */
   @IsString()
   displayName: string;
+
+  /**
+   * True if this group must be specially handled
+   * Used for e.g. "everybody", "all logged in users"
+   * @example false
+   */
   @IsBoolean()
   special: boolean;
 }
 
 export class NoteGroupPermissionEntryDto {
+  /**
+   * Group this permission applies to
+   */
   @ValidateNested()
   group: GroupInfoDto;
+
+  /**
+   * True if the group members are allowed to edit the note
+   * @example false
+   */
   @IsBoolean()
   canEdit: boolean;
 }
 
 export class NoteGroupPermissionUpdateDto {
+  /**
+   * Name of the group this permission should apply to
+   * @example "superheroes"
+   */
   @IsString()
   groupname: string;
+
+  /**
+   * True if the group members should be allowed to edit the note
+   * @example false
+   */
   @IsBoolean()
   canEdit: boolean;
 }
 
 export class NotePermissionsDto {
+  /**
+   * User this permission applies to
+   */
   @ValidateNested()
   owner: UserInfoDto;
+
+  /**
+   * List of users the note is shared with
+   */
   @ValidateNested()
   @IsArray()
   sharedToUsers: NoteUserPermissionEntryDto[];
+
+  /**
+   * List of groups the note is shared with
+   */
   @ValidateNested()
   @IsArray()
   sharedToGroups: NoteGroupPermissionEntryDto[];
 }
 
 export class NotePermissionsUpdateDto {
+  /**
+   * List of users the note should be shared with
+   */
   @IsArray()
   @ValidateNested()
   sharedToUsers: NoteUserPermissionUpdateDto[];
+
+  /**
+   * List of groups the note should be shared with
+   */
   @IsArray()
   @ValidateNested()
   sharedToGroups: NoteGroupPermissionUpdateDto[];

src/notes/note.dto.ts

@@ -9,12 +9,22 @@ import { NoteAuthorshipDto } from './note-authorship.dto';
 import { NoteMetadataDto } from './note-metadata.dto';
 
 export class NoteDto {
+  /**
+   * Markdown content of the note
+   * @example "# I am a heading"
+   */
   @IsString()
   content: string;
 
+  /**
+   * Metadata of the note
+   */
   @ValidateNested()
   metadata: NoteMetadataDto;
 
+  /**
+   * Authorship information of this note
+   */
   @IsArray()
   @ValidateNested({ each: true })
   editedByAtPosition: NoteAuthorshipDto[];

src/revisions/revision-metadata.dto.ts

@@ -8,12 +8,24 @@ import { IsDate, IsNumber } from 'class-validator';
 import { Revision } from './revision.entity';
 
 export class RevisionMetadataDto {
+  /**
+   * ID of this revision
+   * @example 13
+   */
   @IsNumber()
   id: Revision['id'];
 
+  /**
+   * Datestring of the time this revision was created
+   * @example "2020-12-01 12:23:34"
+   */
   @IsDate()
   createdAt: Date;
 
+  /**
+   * Number of characters in this revision
+   * @example 142
+   */
   @IsNumber()
   length: number;
 }

src/revisions/revision.dto.ts

@@ -8,12 +8,30 @@ import { IsDate, IsNumber, IsString } from 'class-validator';
 import { Revision } from './revision.entity';
 
 export class RevisionDto {
+  /**
+   * ID of this revision
+   * @example 13
+   */
   @IsNumber()
   id: Revision['id'];
+
+  /**
+   * Markdown content of the revision
+   * @example "# I am a heading"
+   */
   @IsString()
   content: string;
+
+  /**
+   * Patch from the preceding revision to this one
+   */
   @IsString()
   patch: string;
+
+  /**
+   * Datestring of the time this revision was created
+   * @example "2020-12-01 12:23:34"
+   */
   @IsDate()
   createdAt: Date;
 }

src/users/user-info.dto.ts

@@ -4,15 +4,41 @@
  * SPDX-License-Identifier: AGPL-3.0-only
  */
 
+import { ApiProperty } from '@nestjs/swagger';
 import { IsString } from 'class-validator';
 
 export class UserInfoDto {
+  /**
+   * The username
+   * @example "john.smith"
+   */
   @IsString()
   userName: string;
+
+  /**
+   * The display name
+   * @example "John Smith"
+   */
   @IsString()
   displayName: string;
+
+  /**
+   * URL of the profile picture
+   * @example "https://hedgedoc.example.com/uploads/johnsmith.png"
+   */
+  @ApiProperty({
+    format: 'uri',
+  })
   @IsString()
   photo: string;
+
+  /**
+   * Email address of the user
+   * @example "john.smith@example.com"
+   */
+  @ApiProperty({
+    format: 'email',
+  })
   @IsString()
   email: string;
 }