Add short description in config

[github/Chocobozzz/PeerTube.git] / support / doc / api / openapi.yaml

diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index 8ba784d4bac69482193123e4f08f87f354404631..99bf0fd2de291525355550d927ee63f5f47797a3 100644 (file)
--- a/support/doc/api/openapi.yaml
+++ b/support/doc/api/openapi.yaml
@@ -1,8 +1,12 @@
 swagger: '2.0'
 info:
   title: PeerTube
-  version: 0.0.15-alpha
+  version: 1.0.0-alpha
   description: Federated (ActivityPub) video streaming platform using P2P (BitTorrent) directly in the web browser with WebTorrent and Angular.
+host: peertube.example.com
+basePath: '/api/v1'
+schemes:
+  - https
 paths:
   '/accounts/{id}':
     get:
@@ -18,6 +22,21 @@ paths:
           required: true
           type: string
           description: 'The id of the account'
+        - name: start
+          in: query
+          required: false
+          type: number
+          description: 'starting page'
+        - name: stop
+          in: query
+          required: false
+          type: number
+          description: 'stoping page'
+        - name: sort
+          in: query
+          required: false
+          type: number
+          description: 'sorting'
       responses:
         '200':
           description: successful operation
@@ -59,6 +78,27 @@ paths:
         - application/json
       produces:
         - application/json
+      parameters:
+        - name: state
+          in: path
+          required: true
+          type: string
+          description: 'The id of the account'
+        - name: start
+          in: query
+          required: false
+          type: number
+          description: 'starting page'
+        - name: count
+          in: query
+          required: false
+          type: number
+          description: ''
+        - name: sort
+          in: query
+          required: false
+          type: number
+          description: 'sorting'
       responses:
         '200':
           description: successful operation
@@ -91,6 +131,22 @@ paths:
         - application/json
       produces:
         - application/json
+      parameters:
+        - name: start
+          in: query
+          required: false
+          type: number
+          description: 'starting page'
+        - name: stop
+          in: query
+          required: false
+          type: number
+          description: 'stoping page'
+        - name: sort
+          in: query
+          required: false
+          type: number
+          description: 'sorting'
       responses:
         '200':
           description: successful operation
@@ -106,6 +162,22 @@ paths:
         - application/json
       produces:
         - application/json
+      parameters:
+        - name: start
+          in: query
+          required: false
+          type: number
+          description: 'starting page'
+        - name: stop
+          in: query
+          required: false
+          type: number
+          description: 'stoping page'
+        - name: sort
+          in: query
+          required: false
+          type: number
+          description: 'sorting'
       responses:
         '200':
           description: successful operation
@@ -154,6 +226,22 @@ paths:
         - application/json
       produces:
         - application/json
+      parameters:
+        - name: start
+          in: query
+          required: false
+          type: number
+          description: 'starting page'
+        - name: stop
+          in: query
+          required: false
+          type: number
+          description: 'stoping page'
+        - name: sort
+          in: query
+          required: false
+          type: number
+          description: 'sorting'
       responses:
         '200':
           description: successful operation
@@ -289,6 +377,22 @@ paths:
         - application/json
       produces:
         - application/json
+      parameters:
+        - name: start
+          in: query
+          required: false
+          type: number
+          description: 'starting page'
+        - name: stop
+          in: query
+          required: false
+          type: number
+          description: 'stoping page'
+        - name: sort
+          in: query
+          required: false
+          type: number
+          description: 'sorting'
       responses:
         '200':
           description: successful operation
@@ -331,7 +435,7 @@ paths:
           description: successful operation
           schema:
             $ref: '#/definitions/Avatar'
-  /video:
+  /videos:
     get:
       tags:
         - Video
@@ -339,6 +443,22 @@ paths:
         - application/json
       produces:
         - application/json
+      parameters:
+        - name: start
+          in: query
+          required: false
+          type: number
+          description: 'starting page'
+        - name: stop
+          in: query
+          required: false
+          type: number
+          description: 'stoping page'
+        - name: sort
+          in: query
+          required: false
+          type: number
+          description: 'sorting'
       responses:
         '200':
           description: successful operation
@@ -346,7 +466,7 @@ paths:
             type: array
             items:
               $ref: '#/definitions/Video'
-  /video/categories:
+  /videos/categories:
     get:
       tags:
         - Video
@@ -361,7 +481,7 @@ paths:
             type: array
             items:
               type: string
-  /video/licences:
+  /videos/licences:
     get:
       tags:
         - Video
@@ -376,7 +496,7 @@ paths:
             type: array
             items:
               type: string
-  /video/languages:
+  /videos/languages:
     get:
       tags:
         - Video
@@ -391,7 +511,7 @@ paths:
             type: array
             items:
               type: string
-  /video/privacies:
+  /videos/privacies:
     get:
       tags:
         - Video
@@ -406,7 +526,7 @@ paths:
             type: array
             items:
               type: string
-  /video/search:
+  /videos/search:
     get:
       tags:
         - Video
@@ -414,6 +534,22 @@ paths:
         - application/json
       produces:
         - application/json
+      parameters:
+        - name: start
+          in: query
+          required: false
+          type: number
+          description: 'starting page'
+        - name: stop
+          in: query
+          required: false
+          type: number
+          description: 'stoping page'
+        - name: sort
+          in: query
+          required: false
+          type: number
+          description: 'sorting'
       responses:
         '200':
           description: successful operation
@@ -421,7 +557,7 @@ paths:
             type: array
             items:
               $ref: '#/definitions/Video'
-  "/video/{id}":
+  "/videos/{id}":
     put:
       tags:
         - Video
@@ -474,7 +610,7 @@ paths:
       responses:
         '204':
           description: successful operation
-  "/video/{id}/description":
+  "/videos/{id}/description":
     get:
       tags:
         - Video
@@ -493,7 +629,7 @@ paths:
           description: successful operation
           schema:
             type: string
-  "/video/{id}/views":
+  "/videos/{id}/views":
     post:
       tags:
         - Video
@@ -510,7 +646,7 @@ paths:
       responses:
         '204':
           description: successful operation
-  /video/upload:
+  /videos/upload:
     post:
       tags:
         - Video
@@ -528,7 +664,7 @@ paths:
           description: successful operation
           schema:
             $ref: '#/definitions/VideoUploadResponse'
-  /video/abuse:
+  /videos/abuse:
     get:
       tags:
         - VideoAbuse
@@ -536,6 +672,22 @@ paths:
         - application/json
       produces:
         - application/json
+      parameters:
+        - name: start
+          in: query
+          required: false
+          type: number
+          description: 'starting page'
+        - name: stop
+          in: query
+          required: false
+          type: number
+          description: 'stoping page'
+        - name: sort
+          in: query
+          required: false
+          type: number
+          description: 'sorting'
       responses:
         '200':
           description: successful operation
@@ -543,7 +695,7 @@ paths:
             type: array
             items:
               $ref: '#/definitions/VideoAbuse'
-  "/video/{id}/abuse":
+  "/videos/{id}/abuse":
     post:
       tags:
         - VideoAbuse
@@ -560,7 +712,7 @@ paths:
       responses:
         '204':
           description: successful operation
-  "/video/{videoId}/blacklist":
+  "/videos/{videoId}/blacklist":
     post:
       tags:
         - VideoBlacklist
@@ -593,7 +745,7 @@ paths:
       responses:
         '204':
           description: successful operation
-  /video/blacklist:
+  /videos/blacklist:
     get:
       tags:
         - VideoBlacklist
@@ -601,6 +753,22 @@ paths:
         - application/json
       produces:
         - application/json
+      parameters:
+        - name: start
+          in: query
+          required: false
+          type: number
+          description: 'starting page'
+        - name: stop
+          in: query
+          required: false
+          type: number
+          description: 'stoping page'
+        - name: sort
+          in: query
+          required: false
+          type: number
+          description: 'sorting'
       responses:
         '200':
           description: successful operation
@@ -608,7 +776,7 @@ paths:
             type: array
             items:
               $ref: '#/definitions/VideoBlacklist'
-  /video/channels:
+  /videos/channels:
     get:
       tags:
         - VideoChannel
@@ -616,6 +784,22 @@ paths:
         - application/json
       produces:
         - application/json
+      parameters:
+        - name: start
+          in: query
+          required: false
+          type: number
+          description: 'starting page'
+        - name: stop
+          in: query
+          required: false
+          type: number
+          description: 'stoping page'
+        - name: sort
+          in: query
+          required: false
+          type: number
+          description: 'sorting'
       responses:
         '200':
           description: successful operation
@@ -638,7 +822,7 @@ paths:
       responses:
         '204':
           description: successful operation
-  "/video/channels/{id}":
+  "/videos/channels/{id}":
     get:
       tags:
         - VideoChannel
@@ -693,7 +877,7 @@ paths:
       responses:
         '204':
           description: successful operation
-  /video/accounts/{accountId}/channels:
+  /videos/accounts/{accountId}/channels:
     get:
       tags:
         - VideoChannel
@@ -714,7 +898,7 @@ paths:
             type: array
             items:
               $ref: '#/definitions/VideoChannel'
-  "/video/{videoId}/comment-threads":
+  "/videos/{videoId}/comment-threads":
     get:
       tags:
         - VideoComment
@@ -728,13 +912,26 @@ paths:
           required: true
           type: string
           description: 'The video id '
+        - name: start
+          in: query
+          required: false
+          type: number
+          description: 'starting page'
+        - name: stop
+          in: query
+          required: false
+          type: number
+          description: 'stoping page'
+        - name: sort
+          in: query
+          required: false
+          type: number
+          description: 'sorting'
       responses:
         '200':
           description: successful operation
           schema:
-            items:
-              type: array
-              $ref: '#/definitions/VideoComment'
+            $ref: '#/definitions/CommentThreadResponse'
     post:
       tags:
         - VideoComment
@@ -751,7 +948,9 @@ paths:
       responses:
         '200':
           description: successful operation
-  "/video/{videoId}/comment-threads/{threadId}":
+          schema:
+            $ref: '#/definitions/CommentThreadPostResponse'
+  "/videos/{videoId}/comment-threads/{threadId}":
     get:
       tags:
         - VideoComment
@@ -775,7 +974,7 @@ paths:
           description: successful operation
           schema:
             $ref: '#/definitions/VideoCommentThreadTree'
-  "/video/{videoId}/comments/{commentId}":
+  "/videos/{videoId}/comments/{commentId}":
     post:
       tags:
         - VideoComment
@@ -797,6 +996,8 @@ paths:
       responses:
         '200':
           description: successful operation
+          schema:
+            $ref: '#/definitions/CommentThreadPostResponse'
     delete:
       tags:
         - VideoComment
@@ -818,7 +1019,7 @@ paths:
       responses:
         '204':
           description: successful operation
-  "/video/{id}/rate":
+  "/videos/{id}/rate":
     put:
       tags:
         - VideoRate
@@ -842,8 +1043,6 @@ definitions:
         type: number
       uuid:
         type: string
-      accountName:
-        type: string
       createdAt:
         type: string
       updatedAt:
@@ -868,8 +1067,6 @@ definitions:
         type: boolean
       name:
         type: string
-      serverHost:
-        type: string
       thumbnailPath:
         type: string
       previewPath:
@@ -884,22 +1081,26 @@ definitions:
         type: number
       nsfw:
         type: boolean
+      account:
+        name: string
+        displayName: string
+        url: string
+        host: string
+        avatar:
+          $ref: "#/definitions/Avatar"
   VideoAbuse:
     properties:
       id:
         type: number
       reason:
         type: string
-      reporterUsername:
-        type: string
-      reporterServerHost:
-        type: string
-      videoId:
-        type: number
-      videoUUID:
-        type: string
-      videoName:
-        type: string
+      reporterAccount:
+        $ref: "#/definitions/Account"
+      video:
+        id: number
+        name: string
+        uuid: string
+        url: string
       createdAt:
         type: string
   VideoBlacklist:
@@ -1126,8 +1327,20 @@ definitions:
         type: number
       uuid:
         type: string
+  CommentThreadResponse:
+    properties:
+      total:
+        type: number
+      data:
+        type: array
+        items:
+          $ref: "#/definitions/VideoComment"
+  CommentThreadPostResponse:
+    properties:
+      comment:
+        $ref: "#/definitions/VideoComment"
 
-#input bodies
+#request bodies
   AddUser:
     properties:
       username: