1 files changed, 327 insertions, 64 deletions

diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index 0ab0c71c4..0dc50e403 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
@@ -849,21 +844,8 @@ paths:
                 commentsEnabled:
                   description: Enable or disable comments for this video
                   type: string
-                scheduleUpdate: &ref_0
-                  type: object
-                  properties:
-                    privacy:
-                      type: string
-                      enum:
-                        - Public
-                        - Unlisted
-                      description: Video privacy target
-                    updateAt:
-                      type: string
-                      format: date
-                      description: When to update the video
-                  required:
-                    - updateAt
+                scheduleUpdate:
+                  $ref: '#/components/schemas/VideoScheduledUpdate'
     get:
       summary: Get a video by its id
       tags:
@@ -876,7 +858,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Video'
+                $ref: '#/components/schemas/VideoDetails'
     delete:
       summary: Delete a video by its id
       security:
@@ -1025,7 +1007,7 @@ paths:
                   description: Video preview file
                   type: string
                 privacy:
-                  $ref: '#/components/schemas/VideoPrivacy'
+                  $ref: '#/components/schemas/VideoPrivacySet'
                 category:
                   description: Video category
                   type: string
@@ -1058,7 +1040,8 @@ paths:
                 commentsEnabled:
                   description: Enable or disable comments for this video
                   type: string
-                scheduleUpdate: *ref_0
+                scheduleUpdate:
+                  $ref: '#/components/schemas/VideoScheduledUpdate'
               required:
                 - videofile
                 - channelId
@@ -1129,7 +1112,7 @@ paths:
                   description: Video preview file
                   type: string
                 privacy:
-                  $ref: '#/components/schemas/VideoPrivacy'
+                  $ref: '#/components/schemas/VideoPrivacySet'
                 category:
                   description: Video category
                   type: string
@@ -1162,7 +1145,8 @@ paths:
                 commentsEnabled:
                   description: Enable or disable comments for this video
                   type: string
-                scheduleUpdate: *ref_0
+                scheduleUpdate:
+                  $ref: '#/components/schemas/VideoScheduledUpdate'
               required:
                 - channelId
                 - name
@@ -1247,6 +1231,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
@@ -1275,7 +1311,10 @@ paths:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
       requestBody:
-        $ref: '#/components/requestBodies/VideoChannelInput'
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/VideoChannelCreate'
   '/video-channels/{channelHandle}':
     get:
       summary: Get a video channel by its id
@@ -1302,7 +1341,10 @@ paths:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
       requestBody:
-        $ref: '#/components/requestBodies/VideoChannelInput'
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/VideoChannelUpdate'
     delete:
       summary: Delete a video channel by its id
       security:
@@ -1318,6 +1360,7 @@ paths:
     get:
       summary: Get videos of a video channel by its id
       tags:
+        - Video
         - Video Channel
       parameters:
         - $ref: '#/components/parameters/channelHandle'
@@ -1327,7 +1370,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 +1486,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 +1530,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 +1652,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
@@ -1722,12 +1770,6 @@ components:
         type: array
         items:
           type: string
-  requestBodies:
-    VideoChannelInput:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/VideoChannelInput'
   securitySchemes:
     OAuth2:
       description: >
@@ -1739,7 +1781,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 +1806,129 @@ 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
+    VideoStateConstant:
+      properties:
+        id:
+          type: integer
+          enum:
+            - 1
+            - 2
+            - 3
+          description: 'The video state (Published = 1, to transcode = 2, to import = 3)'
+        label:
+          type: string
+    VideoResolutionConstant:
+      properties:
+        id:
+          type: integer
+          description: 'Video resolution (240, 360, 720 ...)'
+        label:
+          type: string
+    VideoScheduledUpdate:
+      properties:
+        privacy:
+          $ref: '#/components/schemas/VideoPrivacySet'
+          description: Video privacy target
+        updateAt:
+          type: string
+          format: date
+          description: When to update the video
+      required:
+        - updateAt
+    VideoAccountSummary:
+      properties:
+        id:
+          type: number
+        name:
+          type: string
+        displayName:
+          type: string
+        url:
+          type: string
+        host:
+          type: string
+        avatar:
+          nullable: true
+          $ref: '#/components/schemas/Avatar'
+    VideoChannelSummary:
+      properties:
+        id:
+          type: number
+        name:
+          type: string
+        displayName:
+          type: string
+        url:
+          type: string
+        host:
+          type: string
+        avatar:
+          nullable: true
+          $ref: '#/components/schemas/Avatar'
+    PlaylistElement:
+      properties:
+        position:
+          type: number
+        startTimestamp:
+          type: number
+        stopTimestamp:
+          type: number
+    VideoFile:
+      properties:
+        magnetUri:
+          type: string
+        resolution:
+          $ref: '#/components/schemas/VideoResolutionConstant'
+        size:
+          type: number
+          description: 'Video file size in bytes'
+        torrentUrl:
+          type: string
+        torrentDownaloadUrl:
+          type: string
+        fileUrl:
+          type: string
+        fileDownloadUrl:
+          type: string
+        fps:
+          type: number
+    VideoStreamingPlaylists:
+      properties:
+        id:
+          type: number
+        type:
+          type: number
+          enum:
+            - 1
+          description: 'Playlist type (HLS = 1)'
+        playlistUrl:
+          type: string
+        segmentsSha256Url:
+          type: string
+        redundancies:
+          type: array
+          items:
+            type: object
+            properties:
+              baseUrl:
+                type: string
     Video:
       properties:
         id:
@@ -1782,6 +1941,8 @@ components:
           type: string
         updatedAt:
           type: string
+        originallyPublishedAt:
+          type: string
         category:
           $ref: '#/components/schemas/VideoConstantNumber'
         licence:
@@ -1789,7 +1950,7 @@ components:
         language:
           $ref: '#/components/schemas/VideoConstantString'
         privacy:
-          $ref: '#/components/schemas/VideoPrivacy'
+          $ref: '#/components/schemas/VideoPrivacyConstant'
         description:
           type: string
         duration:
@@ -1812,19 +1973,66 @@ components:
           type: number
         nsfw:
           type: boolean
+        waitTranscoding:
+          type: boolean
+          nullable: true
+        state:
+          $ref: '#/components/schemas/VideoStateConstant'
+        scheduledUpdate:
+          nullable: true
+          $ref: '#/components/schemas/VideoScheduledUpdate'
+        blacklisted:
+          nullable: true
+          type: boolean
+        blacklistedReason:
+          nullable: true
+          type: string
         account:
+          $ref: '#/components/schemas/VideoAccountSummary'
+        channel:
+          $ref: '#/components/schemas/VideoChannelSummary'
+        userHistory:
+          nullable: true
           type: object
           properties:
-            name:
-              type: string
-            displayName:
-              type: string
-            url:
+            currentTime:
+              type: number
+        playlistElement:
+          nullable: true
+          $ref: '#/components/schemas/PlaylistElement'
+    VideoDetails:
+      allOf:
+        - $ref: '#/components/schemas/Video'
+        - type: object
+          properties:
+            descriptionPath:
               type: string
-            host:
+            support:
               type: string
-            avatar:
-              $ref: '#/components/schemas/Avatar'
+            channel:
+              $ref: '#/components/schemas/VideoChannel'
+            account:
+              $ref: '#/components/schemas/Account'
+            tags:
+              type: array
+              items:
+                type: string
+            files:
+              type: array
+              items:
+                $ref: '#/components/schemas/VideoFile'
+            commentsEnabled:
+              type: boolean
+            downloadEnabled:
+              type: boolean
+            trackerUrls:
+              type: array
+              items:
+                type: string
+            streamingPlaylists:
+              type: array
+              items:
+                $ref: '#/components/schemas/VideoStreamingPlaylists'
     VideoAbuse:
       properties:
         id:
@@ -1917,6 +2125,12 @@ components:
           type: array
           items:
             $ref: '#/components/schemas/VideoCommentThreadTree'
+    VideoCaption:
+      properties:
+        language:
+          $ref: '#/components/schemas/VideoConstantString'
+        captionPath:
+          type: string
     Avatar:
       properties:
         path:
@@ -1966,6 +2180,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 +2317,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 +2344,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 +2371,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
@@ -2202,14 +2434,45 @@ components:
         email:
           type: string
           description: 'The email of the user '
+        displayName:
+          type: string
+          description: 'The user display name'
+        channel:
+          type: object
+          properties:
+            name:
+              type: string
+              description: 'The default channel name'
+            displayName:
+              type: string
+              description: 'The default channel display name'
+
       required:
         - username
         - password
         - email
-    VideoChannelInput:
+    VideoChannelCreate:
       properties:
         name:
           type: string
+        displayName:
+          type: string
+        description:
+          type: string
+        support:
+          type: string
+      required:
+        - name
+        - displayName
+    VideoChannelUpdate:
+      properties:
+        displayName:
+          type: string
         description:
           type: string
+        support:
+          type: string
+        bulkVideosSupportUpdate:
+          type: boolean
+          description: 'Update all videos support field of this channel'