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

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
+      summary: Get the metadata of a note
-      operationId: updateNoteMetadata
+      operationId: getNoteMetadata
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              "$ref": "#/components/schemas/NoteMetadata"
       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:
+  /notes/{note}/permissions:
-      tags:
+    put:
-        - note
+      tags: [ note ]
-      summary: Get the permissions of a note
+      summary: Set permissions of a note
-      operationId: getNoteMetadata
+      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
+          $ref: "#/components/schemas/UserInfo"
-          description: Username of the owner of the note
+        sharedToUsers:
-        sharedTo:
+          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
+      type: object
-      items:
+      properties:
-        type: object
+        id:
-        properties:
+          type: integer
-          id:
+          description: The id of the revision
-            type: integer
+        createdTime:
-            description: The id of the revision
+          type: string
-          createdTime:
+          description: ISO-timestamp of when the revision was saved. Is also the revision-id.
-            type: string
+        length:
-            description: ISO-timestamp of when the revision was saved. Is also the revision-id.
+          type: integer
-          length:
+          description: Length of the document to the timepoint the revision was saved.
-            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:
+        pinned:
-          type: array
+          type: boolean
-          description: The array that contains history objects.
+          description: Whether the user has pinned this note.
-          items:
-            "$ref": "#/components/schemas/HistoryObject"
   examples:
     markdownExample:
       value: '# Some header\nSome normal text. **Some bold text**'

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',

src/notes/note-metadata.dto.ts

@@ -32,5 +32,5 @@ export class NoteMetadataDto {
   @ValidateNested()
   editedBy: UserInfoDto['userName'][];
   @ValidateNested()
-  permission: NotePermissionsDto;
+  permissions: NotePermissionsDto;
 }

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[];
 }

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),