Merge pull request #512 from codimd/fix/public-api-spec

2024-10-19 13:50:15 -04:00 · 2020-10-29 22:43:28 +01:00 · 2020-10-29 22:43:28 +01:00 · 6b92b012e2
commit 6b92b012e2
parent 0f1cab5006 b7195c563c
5 changed files with 109 additions and 58 deletions
--- a/docs/dev/public_api.yml
+++ b/docs/dev/public_api.yml
@ -47,7 +47,9 @@ paths:
          content:
            application/json:
              schema:
-                "$ref": "#/components/schemas/History"
+                type: array
+                items:
+                  "$ref": "#/components/schemas/History"
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
  /me/history/{note}:
@ -60,11 +62,11 @@ paths:
      description: JSON Object which contains id, title, tags, last visit time and pinned status
      responses:
        '200':
-          description: The list of recently viewed notes and pinned notes.
+          description: Information about the history entry
          content:
            application/json:
              schema:
-                "$ref": "#/components/schemas/HistoryObject"
+                "$ref": "#/components/schemas/History"
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
        '404':
@ -88,7 +90,7 @@ paths:
        content:
          application/json:
            schema:
-              "$ref": "#/components/schemas/HistoryObject"
+              "$ref": "#/components/schemas/HistoryUpdate"
      responses:
        '200':
          description: The new history.
@ -169,7 +171,7 @@ paths:
              markdownExample:
                "$ref": '#/components/examples/markdownExample'
      responses:
-        '200':
+        '201':
          description: Get information about the newly created note.
          content:
            application/json:
@ -212,7 +214,7 @@ paths:
        - note
      summary: Imports some markdown data into a new note with a given alias
      operationId: createNoteWithAlias
-      description: This endpoint equals to the above one except that the alias from the url will be assigned to the note if [FreeURL-mode](https://github.com/codimd/server/tree/master/docs/configuration-env-vars.md#users-and-privileges) is enabled.
+      description: This endpoint creates a new note with the content of the HTTP request body and the alias from the URL parameter.
      requestBody:
        required: true
        description: The content of the note to be imported as markdown.
@ -224,7 +226,7 @@ paths:
              markdownExample:
                "$ref": '#/components/examples/markdownExample'
      responses:
-        '200':
+        '201':
          description: Get information about the newly created note.
          content:
            application/json:
@ -271,7 +273,7 @@ paths:
        - note
      summary: Imports some markdown data into an existing note, creating a new revision
      operationId: createNewRevisionForNote
-      description: This endpoint equals to the above one except that the alias from the url will be assigned to the note if [FreeURL-mode](https://github.com/codimd/server/tree/master/docs/configuration-env-vars.md#users-and-privileges) is enabled.
+      description: This endpoint updates the note content of an existing note. The old content is completely replaced and a new revision is created.
      requestBody:
        required: true
        description: The content of the note to be imported as markdown.
@ -304,20 +306,14 @@ paths:
            text/plain:
              example: my-note
  /notes/{note}/metadata:
-    put:
+    get:
      tags:
        - note
-      summary: Set the permissions of a note
-      operationId: updateNoteMetadata
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              "$ref": "#/components/schemas/NoteMetadata"
+      summary: Get the metadata of a note
+      operationId: getNoteMetadata
      responses:
        '200':
-          description: The updated permissions of the note.
+          description: The metadata of the note.
          content:
            application/json:
              schema:
@ -336,18 +332,24 @@ paths:
          content:
            text/plain:
              example: my-note
-    get:
-      tags:
-        - note
-      summary: Get the permissions of a note
-      operationId: getNoteMetadata
+  /notes/{note}/permissions:
+    put:
+      tags: [ note ]
+      summary: Set permissions of a note
+      operationId: updateNotePermissions
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              "$ref": "#/components/schemas/NotePermissionsUpdate"
      responses:
        '200':
-          description: The permissions of the note.
+          description: The updated permissions of the note.
          content:
            application/json:
              schema:
-                "$ref": "#/components/schemas/NoteMetadata"
+                "$ref": "#/components/schemas/NotePermissions"
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
        '403':
@ -375,7 +377,9 @@ paths:
          content:
            application/json:
              schema:
-                "$ref": "#/components/schemas/NoteRevisionsMetadata"
+                type: array
+                items:
+                  "$ref": "#/components/schemas/NoteRevisionsMetadata"
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
        '403':
@ -524,7 +528,7 @@ paths:
          required: true
          description: ID or alias of the parent note
      responses:
-        '200':
+        '201':
          description: The file was uploaded successfully.
          content:
            application/json:
@ -614,6 +618,15 @@ components:
      properties:
        password:
          type: string
+    GroupInfo:
+      type: object
+      properties:
+        name:
+          type: string
+        displayName:
+          type: string
+        special:
+          type: boolean
    ImageProxyRequest:
      type: object
      properties:
@ -685,9 +698,32 @@ components:
      type: object
      properties:
        owner:
-          type: string
-          description: Username of the owner of the note
-        sharedTo:
+          $ref: "#/components/schemas/UserInfo"
+        sharedToUsers:
+          type: array
+          description: Contains all users that can read the note and a boolean that denotes if they can also edit.
+          items:
+            type: object
+            properties:
+              user:
+                $ref: "#/components/schemas/UserInfo"
+              canEdit:
+                type: boolean
+        sharedToGroups:
+          type: array
+          description: Contains all groups that can read the note and a boolean that denotes if they can also edit.
+          items:
+            type: object
+            properties:
+              group:
+                $ref: "#/components/schemas/GroupInfo"
+              canEdit:
+                type: boolean
+    NotePermissionsUpdate:
+      type: object
+      description: Contains only title, description and tags of a note.
+      properties:
+        sharedToUsers:
          type: array
          description: Contains all usernames that can read the note and a boolean that denotes if they can also edit.
          items:
@ -697,21 +733,28 @@ components:
                type: string
              canEdit:
                type: boolean
-
+        sharedToGroups:
+          type: array
+          description: Contains all groups that can read the note and a boolean that denotes if they can also edit.
+          items:
+            type: object
+            properties:
+              groupname:
+                type: string
+              canEdit:
+                type: boolean
    NoteRevisionsMetadata:
-      type: array
-      items:
-        type: object
-        properties:
-          id:
-            type: integer
-            description: The id of the revision
-          createdTime:
-            type: string
-            description: ISO-timestamp of when the revision was saved. Is also the revision-id.
-          length:
-            type: integer
-            description: Length of the document to the timepoint the revision was saved.
+      type: object
+      properties:
+        id:
+          type: integer
+          description: The id of the revision
+        createdTime:
+          type: string
+          description: ISO-timestamp of when the revision was saved. Is also the revision-id.
+        length:
+          type: integer
+          description: Length of the document to the timepoint the revision was saved.
    NoteRevision:
      type: object
      properties:
@ -812,7 +855,7 @@ components:
          type: boolean
        disconnectSocketQueueLength:
          type: integer
-    HistoryObject:
+    History:
      type: object
      properties:
        metadata:
@ -820,14 +863,12 @@ components:
        pinned:
          type: boolean
          description: Whether the user has pinned this note.
-    History:
+    HistoryUpdate:
      type: object
      properties:
-        history:
-          type: array
-          description: The array that contains history objects.
-          items:
-            "$ref": "#/components/schemas/HistoryObject"
+        pinned:
+          type: boolean
+          description: Whether the user has pinned this note.
  examples:
    markdownExample:
      value: '# Some header\nSome normal text. **Some bold text**'
--- a/src/history/history.service.ts
+++ b/src/history/history.service.ts
@ -20,7 +20,7 @@ export class HistoryService {
          description: 'Very descriptive text.',
          editedBy: [],
          id: 'foobar-barfoo',
-          permission: {
+          permissions: {
            owner: {
              displayName: 'foo',
              userName: 'fooUser',
@ -59,7 +59,7 @@ export class HistoryService {
        description: 'Very descriptive text.',
        editedBy: [],
        id: 'foobar-barfoo',
-        permission: {
+        permissions: {
          owner: {
            displayName: 'foo',
            userName: 'fooUser',
--- a/src/notes/note-metadata.dto.ts
+++ b/src/notes/note-metadata.dto.ts
@ -32,5 +32,5 @@ export class NoteMetadataDto {
  @ValidateNested()
  editedBy: UserInfoDto['userName'][];
  @ValidateNested()
-  permission: NotePermissionsDto;
+  permissions: NotePermissionsDto;
 }
--- a/src/notes/note-permissions.dto.ts
+++ b/src/notes/note-permissions.dto.ts
@ -8,7 +8,7 @@ export class NoteUserPermissionEntryDto {
  canEdit: boolean;
 }

-export class NotePermissionEntryUpdateDto {
+export class NoteUserPermissionUpdateDto {
  @IsString()
  username: string;
  @IsBoolean()
@ -31,6 +31,13 @@ export class NoteGroupPermissionEntryDto {
  canEdit: boolean;
 }

+export class NoteGroupPermissionUpdateDto {
+  @IsString()
+  groupname: string;
+  @IsBoolean()
+  canEdit: boolean;
+}
+
 export class NotePermissionsDto {
  @ValidateNested()
  owner: UserInfoDto;
@ -45,5 +52,8 @@ export class NotePermissionsDto {
 export class NotePermissionsUpdateDto {
  @IsArray()
  @ValidateNested()
-  sharedTo: NotePermissionEntryUpdateDto[];
+  sharedToUsers: NoteUserPermissionUpdateDto[];
+  @IsArray()
+  @ValidateNested()
+  sharedToGroups: NoteGroupPermissionUpdateDto[];
 }
--- a/src/notes/notes.service.ts
+++ b/src/notes/notes.service.ts
@ -37,7 +37,7 @@ export class NotesService {
        description: 'Very descriptive text.',
        editedBy: [],
        id: 'foobar-barfoo',
-        permission: {
+        permissions: {
          owner: {
            displayName: 'foo',
            userName: 'fooUser',
@ -108,7 +108,7 @@ export class NotesService {
      description: NoteUtils.parseDescription(note),
      editedBy: note.authorColors.map(authorColor => authorColor.user.userName),
      // TODO: Extract into method
-      permission: {
+      permissions: {
        owner: this.usersService.toUserDto(note.owner),
        sharedToUsers: note.userPermissions.map(noteUserPermission => ({
          user: this.usersService.toUserDto(noteUserPermission.user),