2 files changed, 118 insertions, 30 deletions

diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index 9963e1d26..a8a064fd0 100644
--- a/support/doc/api/openapi.yaml
+++ b/support/doc/api/openapi.yaml
@@ -38,7 +38,7 @@ info:
     }
     ```
 externalDocs:
-  url: https://docs.joinpeertube.org/api.html
+  url: https://docs.joinpeertube.org/#/api-rest-reference.html
 tags:
   - name: Accounts
     description: >
@@ -99,6 +99,7 @@ x-tagGroups:
   - name: Videos
     tags:
       - Video
+      - Video Caption
       - Video Channel
       - Video Comment
       - Video Following
@@ -152,7 +153,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Video'
+                $ref: '#/components/schemas/VideoListResponse'
       x-code-samples:
         - lang: JavaScript
           source: |
@@ -575,9 +576,7 @@ paths:
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/Video'
+                $ref: '#/components/schemas/VideoListResponse'
   /users/me/subscriptions:
     get:
       summary: Get subscriptions of the current user
@@ -638,9 +637,7 @@ paths:
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/Video'
+                $ref: '#/components/schemas/VideoListResponse'
   '/users/me/subscriptions/{uri}':
     get:
       summary: Get subscription of the current user for a given uri
@@ -730,9 +727,7 @@ paths:
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/Video'
+                $ref: '#/components/schemas/VideoListResponse'
   /videos/categories:
     get:
       summary: Get list of video licences known by the server
@@ -1025,7 +1020,7 @@ paths:
                   description: Video preview file
                   type: string
                 privacy:
-                  $ref: '#/components/schemas/VideoPrivacy'
+                  $ref: '#/components/schemas/VideoPrivacySet'
                 category:
                   description: Video category
                   type: string
@@ -1129,7 +1124,7 @@ paths:
                   description: Video preview file
                   type: string
                 privacy:
-                  $ref: '#/components/schemas/VideoPrivacy'
+                  $ref: '#/components/schemas/VideoPrivacySet'
                 category:
                   description: Video category
                   type: string
@@ -1247,6 +1242,58 @@ paths:
                 type: array
                 items:
                   $ref: '#/components/schemas/VideoBlacklist'
+  /videos/{id}/captions:
+    get:
+      summary: Get list of video's captions
+      tags:
+        - Video Caption
+      parameters:
+        - $ref: '#/components/parameters/id2'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  total:
+                    type: integer
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/VideoCaption'
+  /videos/{id}/captions/{captionLanguage}:
+    put:
+      summary: Add or replace a video caption
+      tags:
+        - Video Caption
+      parameters:
+        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/captionLanguage'
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                captionfile:
+                  description: The file to upload.
+                  type: string
+                  format: binary
+      responses:
+        '204':
+          $ref: '#/paths/~1users~1me/put/responses/204'
+    delete:
+      summary: Delete a video caption
+      tags:
+        - Video Caption
+      parameters:
+        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/captionLanguage'
+      responses:
+        '204':
+          $ref: '#/paths/~1users~1me/put/responses/204'
   /video-channels:
     get:
       summary: Get list of video channels
@@ -1318,6 +1365,7 @@ paths:
     get:
       summary: Get videos of a video channel by its id
       tags:
+        - Video
         - Video Channel
       parameters:
         - $ref: '#/components/parameters/channelHandle'
@@ -1327,7 +1375,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Video'
+                $ref: '#/components/schemas/VideoListResponse'
   '/accounts/{name}/video-channels':
     get:
       summary: Get video channels of an account by its name
@@ -1443,7 +1491,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/CommentThreadPostResponse'
     delete:
-      summary: 'Delete a comment in a comment therad by its id, of a video by its id'
+      summary: 'Delete a comment in a comment thread by its id, of a video by its id'
       security:
         - OAuth2: []
       tags:
@@ -1487,9 +1535,7 @@ paths:
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/Video'
+                $ref: '#/components/schemas/VideoListResponse'
 servers:
   - url: 'https://peertube.cpy.re/api/v1'
     description: Live Test Server (live data - stable version)
@@ -1611,6 +1657,13 @@ components:
       description: The video id or uuid
       schema:
         type: string
+    captionLanguage:
+      name: captionLanguage
+      in: path
+      required: true
+      description: The caption language
+      schema:
+        type: string
     channelHandle:
       name: channelHandle
       in: path
@@ -1739,7 +1792,7 @@ components:
 
         - Have an account with sufficient authorization levels
 
-        - [Generate](https://docs.joinpeertube.org/lang/en/devdocs/rest.html) a
+        - [Generate](https://docs.joinpeertube.org/#/api-rest-getting-started) a
         Bearer Token
 
         - Make Authenticated Requests
@@ -1764,12 +1817,23 @@ components:
           type: string
         label:
           type: string
-    VideoPrivacy:
-      type: string
+    VideoPrivacySet:
+      type: integer
       enum:
-        - Public
-        - Unlisted
-        - Private
+        - 1
+        - 2
+        - 3
+      description: 'The video privacy (Public = 1, Unlisted = 2, Private = 3)'
+    VideoPrivacyConstant:
+      properties:
+        id:
+          type: integer
+          enum:
+            - 1
+            - 2
+            - 3
+        label:
+          type: string
     Video:
       properties:
         id:
@@ -1789,7 +1853,7 @@ components:
         language:
           $ref: '#/components/schemas/VideoConstantString'
         privacy:
-          $ref: '#/components/schemas/VideoPrivacy'
+          $ref: '#/components/schemas/VideoPrivacyConstant'
         description:
           type: string
         duration:
@@ -1917,6 +1981,12 @@ components:
           type: array
           items:
             $ref: '#/components/schemas/VideoCommentThreadTree'
+    VideoCaption:
+      properties:
+        language:
+          $ref: '#/components/schemas/VideoConstantString'
+        captionPath:
+          type: string
     Avatar:
       properties:
         path:
@@ -1966,6 +2036,13 @@ components:
         autoPlayVideo:
           type: boolean
         role:
+          type: integer
+          enum:
+            - 0
+            - 1
+            - 2
+          description: 'The user role (Admin = 0, Moderator = 1, User = 2)'
+        roleLabel:
           type: string
           enum:
             - User
@@ -2096,6 +2173,14 @@ components:
       properties:
         comment:
           $ref: '#/components/schemas/VideoComment'
+    VideoListResponse:
+      properties:
+        total:
+          type: number
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/Video'
     AddUser:
       properties:
         username:
@@ -2115,12 +2200,11 @@ components:
           description: 'The user daily video quota '
         role:
           type: integer
-          format: int32
           enum:
             - 0
             - 1
             - 2
-          description: 'The user role '
+          description: 'The user role (Admin = 0, Moderator = 1, User = 2)'
       required:
         - username
         - password
@@ -2143,8 +2227,12 @@ components:
           type: string
           description: 'The updated daily video quota of the user '
         role:
-          type: string
-          description: 'The updated role of the user '
+          type: integer
+          enum:
+            - 0
+            - 1
+            - 2
+          description: 'The user role (Admin = 0, Moderator = 1, User = 2)'
       required:
         - id
         - email
diff --git a/support/doc/api/quickstart.md b/support/doc/api/quickstart.md
index 00874a1c9..2222be741 100644
--- a/support/doc/api/quickstart.md
+++ b/support/doc/api/quickstart.md
@@ -47,7 +47,7 @@ $ curl -H 'Authorization: Bearer 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0' https
 ```
 
 
-### List videos
+## List videos
 
 ```bash
 $ curl https://peertube.example.com/api/v1/videos