From 963e5b30a9cd9208530c2dbbbdc56b72eb4395c3 Mon Sep 17 00:00:00 2001
From: Chocobozzz <me@florianbigard.com>
Date: Wed, 5 Mar 2025 14:22:17 +0100
Subject: [PATCH] Improve REST API doc

---
 support/doc/api/openapi.yaml | 42 ++++++++++++++++++++++++++++++++----
 1 file changed, 38 insertions(+), 4 deletions(-)

diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index 3c148eaa1..22852cb9c 100644
--- a/support/doc/api/openapi.yaml
+++ b/support/doc/api/openapi.yaml
@@ -7523,12 +7523,13 @@ components:
       name: nsfw
       in: query
       required: false
-      description: whether to include nsfw videos, if any
+      description: Whether to include nsfw videos, if any. The default value is set by the admin.
       schema:
         type: string
         enum:
         - 'true'
         - 'false'
+        - 'both'
     isLocal:
       name: isLocal
       in: query
@@ -7555,8 +7556,27 @@ components:
       in: query
       required: false
       schema:
-        $ref: '#/components/schemas/VideoPrivacySet'
-      description: '**PeerTube >= 4.0** Display only videos in this specific privacy/privacies'
+        allOf:
+         - $ref: '#/components/schemas/VideoPrivacySet'
+      description: >
+        **Only administrators and moderators can use this parameter**
+
+
+        Display only videos in this specific privacy/privacies. By default, list public videos for anonymous users and public/internal videos for authenticated users
+
+        - `1` PUBLIC
+
+        - `2` UNLISTED
+
+        - `3` PRIVATE
+
+        - `4` INTERNAL
+
+        - `5` PASSWORD_PROTECTED
+      examples:
+        password:
+          value: 5
+          summary: Display only password protected videos
     excludeAlreadyWatched:
       name: excludeAlreadyWatched
       in: query
@@ -7600,11 +7620,14 @@ components:
         - 8
         - 16
         - 32
+        - 64
+        - 128
       description: >
         **Only administrators and moderators can use this parameter**
 
 
-        Include additional videos in results (can be combined using bitwise or operator)
+        Include additional videos in results (can be combined using bitwise or operator).
+        By default PeerTube only list published videos that are not blocked.
 
         - `0` NONE
 
@@ -7619,6 +7642,17 @@ components:
         - `16` CAPTIONS
 
         - `32` VIDEO SOURCE
+
+        - `64`: AUTOMATIC_TAGS
+
+        - `128`: TAGS
+      examples:
+        includeAll:
+          value: 3
+          summary: Include not published and blacklisted videos (1 + 2)
+        includeAllWithFiles:
+          value: 24
+          summary: Add files and captions to video JSON representation (8 + 16)
     subscriptionsUris:
       name: uris
       in: query