Merge pull request #3179 from nichwall/api_spec_opml

Update: podcast opml endpoints

docs/controllers/PodcastController.yaml

@@ -58,14 +58,14 @@ paths:
         404:
           description: Not found
 
-  /api/podcasts/opml:
+  /api/podcasts/opml/parse:
     post:
       summary: Get feeds from OPML text
+      description: Parse OPML text and return an array of feeds
       operationId: getFeedsFromOPMLText
       tags:
         - Podcasts
       requestBody:
-        required: true
         content:
           application/json:
             schema:
@@ -73,20 +73,58 @@ paths:
               properties:
                 opmlText:
                   type: string
-                  description: The OPML text containing podcast feeds
       responses:
-        200:
+        '200':
-          description: Successfully retrieved feeds from OPML text
+          description: Successfully parsed OPML text and returned feeds
           content:
             application/json:
               schema:
+                type: object
+                properties:
+                  feeds:
                     type: array
                     items:
-                  $ref: '../objects/mediaTypes/Podcast.yaml#/components/schemas/Podcast'
+                      type: object
-        400:
+                      properties:
-          description: Bad request
+                        title:
-        403:
+                          type: string
-          description: Forbidden
+                        feedUrl:
+                          type: string
+        '400':
+          description: Bad request, OPML text not provided
+        '403':
+          description: Forbidden, user is not admin
+  /api/podcasts/opml/create:
+    post:
+      summary: Bulk create podcasts from OPML feed URLs
+      operationId: bulkCreatePodcastsFromOpmlFeedUrls
+      tags:
+        - Podcasts
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                feeds:
+                  type: array
+                  items:
+                    type: string
+                libraryId:
+                  $ref: '../objects/Library.yaml#/components/schemas/libraryId'
+                folderId:
+                  $ref: '../objects/Folder.yaml#/components/schemas/folderId'
+                autoDownloadEpisodes:
+                  $ref: '../objects/mediaTypes/Podcast.yaml#/components/schemas/autoDownloadEpisodes'
+      responses:
+        '200':
+          description: Successfully created podcasts from feed URLs
+        '400':
+          description: Bad request, invalid request body
+        '403':
+          description: Forbidden, user is not admin
+        '404':
+          description: Folder not found
 
   /api/podcasts/{id}/checknew:
     parameters:

docs/objects/mediaTypes/Podcast.yaml

@@ -11,6 +11,9 @@ components:
       nullable: true
       format: 'pod_[a-z0-9]{18}'
       example: pod_o78uaoeuh78h6aoeif
+    autoDownloadEpisodes:
+      type: boolean
+      description: Whether episodes are automatically downloaded.
 
     Podcast:
       type: object
@@ -37,8 +40,7 @@ components:
           items:
             $ref: '../entities/PodcastEpisode.yaml#/components/schemas/PodcastEpisode'
         autoDownloadEpisodes:
-          type: boolean
+          $ref: '#/components/schemas/autoDownloadEpisodes'
-          description: Whether episodes are automatically downloaded.
         autoDownloadSchedule:
           type: string
           description: The schedule for automatic episode downloads, in cron format.

docs/openapi.json

@@ -1589,23 +1589,22 @@
         }
       }
     },
-    "/api/podcasts/opml": {
+    "/api/podcasts/opml/parse": {
       "post": {
         "summary": "Get feeds from OPML text",
+        "description": "Parse OPML text and return an array of feeds",
         "operationId": "getFeedsFromOPMLText",
         "tags": [
           "Podcasts"
         ],
         "requestBody": {
-          "required": true,
           "content": {
             "application/json": {
               "schema": {
                 "type": "object",
                 "properties": {
                   "opmlText": {
-                    "type": "string",
+                    "type": "string"
-                    "description": "The OPML text containing podcast feeds"
                   }
                 }
               }
@@ -1614,23 +1613,85 @@
         },
         "responses": {
           "200": {
-            "description": "Successfully retrieved feeds from OPML text",
+            "description": "Successfully parsed OPML text and returned feeds",
             "content": {
               "application/json": {
                 "schema": {
+                  "type": "object",
+                  "properties": {
+                    "feeds": {
                       "type": "array",
                       "items": {
-                    "$ref": "#/components/schemas/Podcast"
+                        "type": "object",
+                        "properties": {
+                          "title": {
+                            "type": "string"
+                          },
+                          "feedUrl": {
+                            "type": "string"
+                          }
+                        }
+                      }
+                    }
                   }
                 }
               }
             }
           },
           "400": {
-            "description": "Bad request"
+            "description": "Bad request, OPML text not provided"
           },
           "403": {
-            "description": "Forbidden"
+            "description": "Forbidden, user is not admin"
+          }
+        }
+      }
+    },
+    "/api/podcasts/opml/create": {
+      "post": {
+        "summary": "Bulk create podcasts from OPML feed URLs",
+        "operationId": "bulkCreatePodcastsFromOpmlFeedUrls",
+        "tags": [
+          "Podcasts"
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "feeds": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  },
+                  "libraryId": {
+                    "$ref": "#/components/schemas/libraryId"
+                  },
+                  "folderId": {
+                    "$ref": "#/components/schemas/folderId"
+                  },
+                  "autoDownloadEpisodes": {
+                    "$ref": "#/components/schemas/autoDownloadEpisodes"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successfully created podcasts from feed URLs"
+          },
+          "400": {
+            "description": "Bad request, invalid request body"
+          },
+          "403": {
+            "description": "Forbidden, user is not admin"
+          },
+          "404": {
+            "description": "Folder not found"
           }
         }
       }
@@ -3856,6 +3917,10 @@
           }
         }
       },
+      "autoDownloadEpisodes": {
+        "type": "boolean",
+        "description": "Whether episodes are automatically downloaded."
+      },
       "Podcast": {
         "type": "object",
         "description": "A podcast containing multiple episodes.",
@@ -3889,8 +3954,7 @@
             }
           },
           "autoDownloadEpisodes": {
-            "type": "boolean",
+            "$ref": "#/components/schemas/autoDownloadEpisodes"
-            "description": "Whether episodes are automatically downloaded."
           },
           "autoDownloadSchedule": {
             "type": "string",

docs/root.yaml

@@ -57,8 +57,10 @@ paths:
     $ref: './controllers/PodcastController.yaml#/paths/~1api~1podcasts'
   /api/podcasts/feed:
     $ref: './controllers/PodcastController.yaml#/paths/~1api~1podcasts~1feed'
-  /api/podcasts/opml:
+  /api/podcasts/opml/parse:
-    $ref: './controllers/PodcastController.yaml#/paths/~1api~1podcasts~1opml'
+    $ref: './controllers/PodcastController.yaml#/paths/~1api~1podcasts~1opml~1parse'
+  /api/podcasts/opml/create:
+    $ref: './controllers/PodcastController.yaml#/paths/~1api~1podcasts~1opml~1create'
   /api/podcasts/{id}/checknew:
     $ref: './controllers/PodcastController.yaml#/paths/~1api~1podcasts~1{id}~1checknew'
   /api/podcasts/{id}/clear-queue: