Merge branch 'master' into admin/users

public/openapi/write.yaml

@@ -21,262 +21,23 @@ info:
   license:
     name: GPL-3.0
 servers:
-  - url: /api/v1
+  - url: /api/v3
 tags:
   - name: users
     description: 'Account related calls (create, modify, delete, etc.)'
   - name: categories
     description: Administrative calls to manage categories
 paths:
-  '/users/{uid}':
-    delete:
-      tags:
-        - users
-      summary: delete a single user account
-      parameters:
-        - in: path
-          name: uid
-          schema:
-            type: integer
-          required: true
-          description: uid of the user to delete
-      responses:
-        '200':
-          description: user account deleted
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  status:
-                    $ref: components/schemas/Status.yaml#/Status
-                  response:
-                    type: object
-    put:
-      tags:
-        - users
-      summary: update a user account
-      parameters:
-        - in: path
-          name: uid
-          schema:
-            type: integer
-          required: true
-          description: uid of the user to update
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: components/schemas/UserRequest.yaml#/UserRequest
-      responses:
-        '200':
-          description: user profile updated
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  status:
-                    $ref: components/schemas/Status.yaml#/Status
-                  response:
-                    $ref: components/schemas/UserObj.yaml#/UserObj
-        '401':
-          $ref: components/responses/401.yaml#/401
-        '403':
-          $ref: components/responses/403.yaml#/403
-        '426':
-          $ref: components/responses/426.yaml#/426
-        '500':
-          $ref: components/responses/500.yaml#/500
-  '/users/{uid}/password':
-    put:
-      tags:
-        - users
-      summary: change a user's password
-      parameters:
-        - in: path
-          name: uid
-          schema:
-            type: integer
-          required: true
-          description: uid of the user to update
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                currentPassword:
-                  type: string
-                  description: test
-                  example: oldp455word
-                newPassword:
-                  type: string
-                  example: s3cre7password
-              required:
-                - newPassword
-      responses:
-        '200':
-          description: user profile updated
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  status:
-                    $ref: components/schemas/Status.yaml#/Status
-                  response:
-                    type: object
-  '/users/{uid}/follow':
-    post:
-      tags:
-        - users
-      summary: follow a user
-      parameters:
-        - in: path
-          name: uid
-          schema:
-            type: integer
-          required: true
-          description: uid of the user to follow
-      responses:
-        '200':
-          description: successfully followed user
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  status:
-                    $ref: components/schemas/Status.yaml#/Status
-                  response:
-                    type: object
-    delete:
-      tags:
-        - users
-      summary: unfollows a user
-      parameters:
-        - in: path
-          name: uid
-          schema:
-            type: integer
-          required: true
-          description: uid of the user to unfollow
-      responses:
-        '200':
-          description: successfully unfollowed user
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  status:
-                    $ref: components/schemas/Status.yaml#/Status
-                  response:
-                    type: object
-  '/users/{uid}/ban':
-    put:
-      tags:
-        - users
-      summary: ban a user
-      parameters:
-        - in: path
-          name: uid
-          schema:
-            type: integer
-          required: true
-          description: uid of the user to ban
-      requestBody:
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                until:
-                  type: number
-                  description: UNIX timestamp of the ban expiry
-                  example: 1585775608076
-                reason:
-                  type: string
-                  example: the reason for the ban
-      responses:
-        '200':
-          description: successfully banned user
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  status:
-                    $ref: components/schemas/Status.yaml#/Status
-                  response:
-                    type: object
-    delete:
-      tags:
-        - users
-      summary: unbans a user
-      parameters:
-        - in: path
-          name: uid
-          schema:
-            type: integer
-          required: true
-          description: uid of the user to unban
-      responses:
-        '200':
-          description: successfully unbanned user
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  status:
-                    $ref: components/schemas/Status.yaml#/Status
-                  response:
-                    type: object
-  '/users/{uid}/tokens':
-    post:
-      tags:
-        - users
-      summary: generate a user token
-      description: This route can only be used to generate tokens for the same user. In other words, you cannot use this route to generate a token for a different user than the one you are authenticated as.
-      responses:
-        '200':
-          description: successfully generated a user token
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  status:
-                    $ref: components/schemas/Status.yaml#/Status
-                  response:
-                    type: object
-    delete:
-      tags:
-        - users
-      summary: delete user token
-      parameters:
-        - in: path
-          name: token
-          schema:
-            type: string
-          required: true
-          description: a valid API token
-      responses:
-        '200':
-          description: successfully deleted user token
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  status:
-                    $ref: components/schemas/Status.yaml#/Status
-                  response:
-                    type: object
+  /users/{uid}:
+    $ref: 'write/users/uid.yaml'
+  /users/{uid}/password:
+    $ref: 'write/users/uid/password.yaml'
+  /users/{uid}/follow:
+    $ref: 'write/users/uid/follow.yaml'
+  /users/{uid}/ban:
+    $ref: 'write/users/uid/ban.yaml'
+  /users/{uid}/tokens:
+    $ref: 'write/users/uid/tokens.yaml'
   /categories/:
     $ref: 'write/categories.yaml'
   /groups/:

public/openapi/write/users/uid.yaml

@@ -0,0 +1,60 @@
+delete:
+  tags:
+    - users
+  summary: delete a single user account
+  parameters:
+    - in: path
+      name: uid
+      schema:
+        type: integer
+      required: true
+      description: uid of the user to delete
+  responses:
+    '200':
+      description: user account deleted
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                $ref: ../../components/schemas/Status.yaml#/Status
+              response:
+                type: object
+put:
+  tags:
+    - users
+  summary: update a user account
+  parameters:
+    - in: path
+      name: uid
+      schema:
+        type: integer
+      required: true
+      description: uid of the user to update
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: ../../components/schemas/UserRequest.yaml#/UserRequest
+  responses:
+    '200':
+      description: user profile updated
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                $ref: ../../components/schemas/Status.yaml#/Status
+              response:
+                $ref: ../../components/schemas/UserObj.yaml#/UserObj
+    '401':
+      $ref: ../../components/responses/401.yaml#/401
+    '403':
+      $ref: ../../components/responses/403.yaml#/403
+    '426':
+      $ref: ../../components/responses/426.yaml#/426
+    '500':
+      $ref: ../../components/responses/500.yaml#/500

public/openapi/write/users/uid/ban.yaml

@@ -0,0 +1,59 @@
+put:
+  tags:
+    - users
+  summary: ban a user
+  parameters:
+    - in: path
+      name: uid
+      schema:
+        type: integer
+      required: true
+      description: uid of the user to ban
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            until:
+              type: number
+              description: UNIX timestamp of the ban expiry
+              example: 1585775608076
+            reason:
+              type: string
+              example: the reason for the ban
+  responses:
+    '200':
+      description: successfully banned user
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                $ref: ../../../components/schemas/Status.yaml#/Status
+              response:
+                type: object
+delete:
+  tags:
+    - users
+  summary: unbans a user
+  parameters:
+    - in: path
+      name: uid
+      schema:
+        type: integer
+      required: true
+      description: uid of the user to unban
+  responses:
+    '200':
+      description: successfully unbanned user
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                $ref: ../../../components/schemas/Status.yaml#/Status
+              response:
+                type: object