From 2ad85d5fdccca3c6e578a74316cb8d458a5d9e52 Mon Sep 17 00:00:00 2001
From: sct <sctsnipe@gmail.com>
Date: Wed, 3 Feb 2021 01:45:48 +0000
Subject: [PATCH] docs(api): update api schema to have editable server url +
 other touchups [skip ci]

---
 overseerr-api.yml | 90 ++++++++++++++++++++++++-----------------------
 1 file changed, 46 insertions(+), 44 deletions(-)

diff --git a/overseerr-api.yml b/overseerr-api.yml
index c8e7cea43..bacf20525 100644
--- a/overseerr-api.yml
+++ b/overseerr-api.yml
@@ -2,8 +2,43 @@ openapi: '3.0.2'
 info:
   title: 'Overseerr API'
   version: '1.0.0'
+  description: |
+    This is the documentation for the Overseerr API backend.
+
+    Two primary authentication methods are supported:
+
+    - **Cookie Authentication**: A valid login to the `/auth/login` or `/auth/local` will generate a valid authentication cookie.
+    - **API Key Authentication**: Login is also possible by passing an `X-Api-Key` header along with a valid API Key generated by Overseerr.
+tags:
+  - name: public
+    description: Public API endpoints requiring no authentication.
+  - name: settings
+    description: Endpoints related to Overseerr's settings and configuration.
+  - name: auth
+    description: Endpoints related to logging in or out, and the currently authenticated user.
+  - name: users
+    description: Endpoints related to user management.
+  - name: search
+    description: Endpoints related to search and discovery.
+  - name: request
+    description: Endpoints related to request management.
+  - name: movies
+    description: Endpoints related to retrieving movies and their details.
+  - name: tv
+    description: Endpoints related to retrieving TV series and their details.
+  - name: person
+    description: Endpoints related to retrieving Person details.
+  - name: media
+    description: Endpoints related to media management.
+  - name: collection
+    description: Endpoints related to retrieving Collection details.
+  - name: service
+    description: Endpoinst related to getting Service (Radarr/Sonarr) details.
 servers:
-  - url: /api/v1
+  - url: '{server}/api/v1'
+    variables:
+      server:
+        default: http://localhost:5055
 
 components:
   schemas:
@@ -119,17 +154,6 @@ components:
         - machineId
         - ip
         - port
-    PlexStatus:
-      type: object
-      properties:
-        settings:
-          $ref: '#/components/schemas/PlexSettings'
-        status:
-          type: number
-          example: 200
-        message:
-          type: string
-          example: 'OK'
     PlexConnection:
       type: object
       properties:
@@ -394,29 +418,6 @@ components:
         initialized:
           type: boolean
           example: false
-    AllSettings:
-      type: object
-      properties:
-        main:
-          $ref: '#/components/schemas/MainSettings'
-        plex:
-          $ref: '#/components/schemas/PlexSettings'
-        radarr:
-          type: array
-          items:
-            $ref: '#/components/schemas/RadarrSettings'
-        sonarr:
-          type: array
-          items:
-            $ref: '#/components/schemas/SonarrSettings'
-        public:
-          $ref: '#/components/schemas/PublicSettings'
-      required:
-        - main
-        - plex
-        - radarr
-        - sonarr
-        - public
     MovieResult:
       type: object
       required:
@@ -590,7 +591,7 @@ components:
           readOnly: true
         imdbId:
           type: string
-          example: 123
+          example: 'tt123'
         adult:
           type: boolean
         backdropPath:
@@ -2557,7 +2558,8 @@ paths:
             application/json:
               schema:
                 type: array
-                $ref: '#/components/schemas/User'
+                items:
+                  $ref: '#/components/schemas/User'
 
   /user/import-from-plex:
     post:
@@ -3024,7 +3026,7 @@ paths:
           name: requestId
           description: Request ID
           required: true
-          example: 1
+          example: '1'
           schema:
             type: string
       responses:
@@ -3044,7 +3046,7 @@ paths:
           name: requestId
           description: Request ID
           required: true
-          example: 1
+          example: '1'
           schema:
             type: string
       responses:
@@ -3064,7 +3066,7 @@ paths:
           name: requestId
           description: Request ID
           required: true
-          example: 1
+          example: '1'
           schema:
             type: string
       responses:
@@ -3086,7 +3088,7 @@ paths:
           required: true
           schema:
             type: string
-            example: 1
+            example: '1'
       responses:
         '200':
           description: Retry triggered
@@ -3110,7 +3112,7 @@ paths:
           required: true
           schema:
             type: string
-            example: 1
+            example: '1'
         - in: path
           name: status
           description: New status
@@ -3582,7 +3584,7 @@ paths:
           name: mediaId
           description: Media ID
           required: true
-          example: 1
+          example: '1'
           schema:
             type: string
       responses:
@@ -3599,7 +3601,7 @@ paths:
           name: mediaId
           description: Media ID
           required: true
-          example: 1
+          example: '1'
           schema:
             type: string
         - in: path