Schema updates from August 3 (#1)

* Update: formatting * Fix: libraryItemController `play` endpoint + Endpoints cannot have optional path parameters + Moved schemas to `components` section * Fix: MeController optional path parameters * Fix: Books do not have `episodeId` in `mediaProgress` * Fix: `PlaybackSession` oneOf between book and podcast * Update: bundled spec * Fix: `allowReserved` in LibraryItem include query * Add: tags to AuthController endpoints * Fix: summary of play endpoints * Update: bundled spec
Vito0912 · Aug 4, 2024 · 3a91092 · 3a91092
1 parent 7274b87
commit 3a91092
Show file tree

Hide file tree

Showing 13 changed files with 553 additions and 433 deletions.
diff --git a/docs/controllers/AuthController.yaml b/docs/controllers/AuthController.yaml
@@ -4,6 +4,8 @@ paths:
       summary: Login to the server
       description: Logs in a client to the server, returning information about the user and server.
       operationId: login
+      tags:
+        - Auth
       requestBody:
         required: true
         content:
@@ -15,9 +17,6 @@ paths:
                   $ref: '../objects/entities/User.yaml#/components/schemas/username'
                 password:
                   $ref: '../objects/entities/User.yaml#/components/schemas/password'
-              required:
-                - username
-                - password
       responses:
         '200':
           description: Success
@@ -40,6 +39,8 @@ paths:
       summary: Logout from the server
       description: Logs out a client from the server. If the socketId parameter is provided, the server removes the socket from the client list.
       operationId: logout
+      tags:
+        - Auth
       requestBody:
         required: true
         content:

diff --git a/docs/controllers/LibraryItemController.yaml b/docs/controllers/LibraryItemController.yaml
@@ -1,3 +1,69 @@
+components:
+  schemas:
+    parameters:
+      include:
+        in: query
+        name: include
+        description: A comma separated list of what to include with the library item. The options are progress, rssfeed, authors (for books), and downloads (for podcasts). expanded must be 1 for include to have an effect.
+        allowReserved: true
+        schema:
+          type: string
+      expanded:
+        in: query
+        name: expanded
+        description: Whether to return Library Item Expanded instead. 0 for false, 1 for true.
+        schema:
+          type: integer
+          example: 1
+      episode:
+        in: query
+        name: episode
+        description: If requesting progress for a podcast, the episode ID to get progress for.
+        schema:
+          $ref: '../objects/mediaTypes/Podcast.yaml#/components/schemas/podcastId'
+      deviceInfo:
+        in: query
+        name: deviceInfo
+        description: The device information to send to the server.
+        schema:
+          $ref: '../objects/entities/Device.yaml#/components/schemas/deviceInfo'
+      forceDirectPlay:
+        in: query
+        name: forceDirectPlay
+        description: Whether to force direct play of the library item.
+        schema:
+          type: boolean
+          example: false
+      forceTranscode:
+        in: query
+        name: forceTranscode
+        description: Whether to force transcoding of the library item.
+        schema:
+          type: boolean
+          example: false
+      supportedMimeTypes:
+        in: query
+        name: supportedMimeTypes
+        description: The supported mime types for the device.
+        schema:
+          type: array
+          items:
+            type: string
+      mediaPlayer:
+        in: query
+        name: mediaPlayer
+        description: The media player to use.
+        schema:
+          type: string
+  responses:
+    libraryItem404:
+      description: Not Found
+      content:
+        text/html:
+          schema:
+            type: string
+            description: The library item does not exist.
+            example: Not Found
 paths:
   /api/items/{id}:
     parameters:
@@ -14,32 +80,50 @@ paths:
       tags:
         - LibraryItem
       parameters:
-        - in: query
-          name: include
-          description: A comma separated list of what to include with the library item. The options are progress, rssfeed, authors (for books), and downloads (for podcasts). expanded must be 1 for include to have an effect.
-          schema:
-            type: string
-        - in: query
-          name: expanded
-          description: Whether to return Library Item Expanded instead. 0 for false, 1 for true.
-          schema:
-              type: integer
-              example: 1
-        - in: query
-          name: episode
-          description: If requesting progress for a podcast, the episode ID to get progress for.
-          schema:
-              $ref: '../objects/mediaTypes/Podcast.yaml#/components/schemas/podcastId'
+        - $ref: '#/components/schemas/parameters/include'
+        - $ref: '#/components/schemas/parameters/expanded'
+        - $ref: '#/components/schemas/parameters/episode'
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                description: TODO
+                oneOf:
+                  - $ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItem'
+        '404':
+          $ref: '#/components/responses/libraryItem404'
+  /api/items/{id}/play:
+    parameters:
+      - name: id
+        in: path
+        description: The ID of the library item.
+        required: true
+        schema:
+          $ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItemId'
+    post:
+      operationId: playLibraryItem
+      summary: Play a library item
+      description: Play a library item by ID.
+      tags:
+        - LibraryItem
+      parameters:
+        - $ref: '#/components/schemas/parameters/deviceInfo'
+        - $ref: '#/components/schemas/parameters/forceDirectPlay'
+        - $ref: '#/components/schemas/parameters/forceTranscode'
+        - $ref: '#/components/schemas/parameters/supportedMimeTypes'
+        - $ref: '#/components/schemas/parameters/mediaPlayer'
       responses:
         '200':
-            description: OK
-            content:
-                application/json:
-                  schema:
-                      type: object
-                      description: TODO
-                      oneOf:
-                        - $ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItem'
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSessionExpanded'
+        '404':
+          $ref: '#/components/responses/libraryItem404'
   /api/items/{id}/play/{episodeId}:
     parameters:
       - name: id
@@ -51,57 +135,27 @@ paths:
       - name: episodeId
         in: path
         description: The ID of the episode to play.
-        required: false
+        required: true
         schema:
           $ref: '../objects/mediaTypes/Podcast.yaml#/components/schemas/podcastId'
     post:
-      operationId: playLibraryItem
-      summary: Play a library item.
-      description: Play a library item.
+      operationId: playLibraryItemPodcastEpisode
+      summary: Play a podcast episode
+      description: Play a podcast by library item ID and episode ID.
       tags:
         - LibraryItem
       parameters:
-        - in: query
-          name: deviceInfo
-          description: The device information to send to the server.
-          schema:
-              $ref: '../objects/entities/Device.yaml#/components/schemas/deviceInfo'
-        - in: query
-          name: forceDirectPlay
-          description: Whether to force direct play of the library item.
-          schema:
-              type: boolean
-              example: false
-        - in: query
-          name: forceTranscode
-          description: Whether to force transcoding of the library item.
-          schema:
-              type: boolean
-              example: false
-        - in: query
-          name: supportedMimeTypes
-          description: The supported mime types for the device.
-          schema:
-                type: array
-                items:
-                    type: string
-        - in: query
-          name: mediaPlayer
-          description: The media player to use.
-          schema:
-              type: string
+        - $ref: '#/components/schemas/parameters/deviceInfo'
+        - $ref: '#/components/schemas/parameters/forceDirectPlay'
+        - $ref: '#/components/schemas/parameters/forceTranscode'
+        - $ref: '#/components/schemas/parameters/supportedMimeTypes'
+        - $ref: '#/components/schemas/parameters/mediaPlayer'
       responses:
         '200':
-            description: OK
-            content:
-                application/json:
-                  schema:
-                      $ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSessionExpanded'
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSessionExpanded'
         '404':
-            description: Not Found
-            content:
-                text/html:
-                  schema:
-                      type: string
-                      description: The library item does not have any audio tracks to play.
-                      example: Not Found
+          $ref: '#/components/responses/libraryItem404'