WIP: feat: add more OpenAPI specs

docs/controllers/AuthController.yaml

@@ -0,0 +1,69 @@
+paths:
+  /login:
+    post:
+      summary: Login to the server
+      description: Logs in a client to the server, returning information about the user and server.
+      operationId: login
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                username:
+                  $ref: '../objects/entities/User.yaml#/components/schemas/username'
+                password:
+                  $ref: '../objects/entities/User.yaml#/components/schemas/password'
+              required:
+                - username
+                - password
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  user:
+                    $ref: '../objects/entities/User.yaml#/components/schemas/user'
+        '401':
+          description: Unauthorized - Invalid username or password.
+          content:
+            text/html:
+              schema:
+                type: string
+                example: Unauthorized
+  /logout:
+    post:
+      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
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                socketId:
+                  $ref: '../objects/entities/User.yaml#/components/schemas/socketId'
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                    example: Success
+        '401':
+          description: Unauthorized
+          content:
+            text/html:
+              schema:
+                type: string
+                example: Unauthorized

docs/controllers/LibraryController.yaml

@@ -167,6 +167,7 @@ paths:
       parameters:
         - in: query
           name: include
+          description: A comma separated list of what to include with the library item. The only current option is filterdata.
           schema:
             type: string
         - $ref: '../schemas.yaml#/components/parameters/minified'

docs/controllers/LibraryItemController.yaml

@@ -0,0 +1,41 @@
+paths:
+  /api/items/{id}:
+    parameters:
+      - name: id
+        in: path
+        description: The ID of the library item.
+        required: true
+        schema:
+          $ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItemId'
+    get:
+      operationId: getLibraryItem
+      summary: Get a single library item by ID on server.
+      description: Get a single library item by ID on server.
+      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'
+      responses:
+        '200':
+            description: OK
+            content:
+                application/json:
+                  schema:
+                      description: TODO - Add minified library item object
+                      oneOf:
+                        - $ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItemBase'

docs/objects/Bookmarks.yaml

@@ -0,0 +1,18 @@
+components:
+  schemas:
+    time:
+      type: integer
+      description: The time (in ms since POSIX epoch) when the bookmark was created.
+      example: 1616239000
+    bookmark:
+      properties:
+        libraryItemId:
+          $ref: 'LibraryItem.yaml#/components/schemas/libraryItemId'
+        title:
+          type: string
+          description: The title of the bookmark.
+          example: Chapter 1
+        time:
+          $ref: '#/components/schemas/time'
+        createdAt:
+          $ref: '../schemas.yaml#/components/schemas/createdAt'

docs/objects/LibraryItem.yaml

@@ -55,6 +55,8 @@ components:
           type: boolean
         mediaType:
           $ref: './mediaTypes/media.yaml#/components/schemas/mediaType'
+        media:
+          $ref: './mediaTypes/Book.yaml#/components/schemas/bookMinified'
     libraryItemMinified:
       type: object
       description: A single item on the server, like a book or podcast. Minified media format.

docs/objects/Media.yaml

@@ -0,0 +1,42 @@
+components:
+  schemas:
+    mediaProgressId:
+      type: string
+      description: The ID of the media progress.
+      example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
+      format: uuid
+    mediaProgress:
+      type: object
+      properties:
+        id:
+          $ref: '#/components/schemas/mediaProgressId'
+        libraryItemId:
+          $ref: 'LibraryItem.yaml#/components/schemas/libraryItemId'
+        episodeId:
+          $ref: 'mediaTypes/Podcast.yaml#/components/schemas/podcastId'
+        duration:
+          $ref: '../schemas.yaml#/components/schemas/durationSec'
+        progress:
+          type: number
+          description: The user's progress in the media item.
+          example: 0.5
+        currentTime:
+          type: number
+          description: The user's current time in the media item.
+          example: 0.5
+        isFinished:
+          type: boolean
+          description: Whether the user has finished the media item.
+          example: false
+        hideFromContinueListening:
+          type: boolean
+          description: Whether the media item should be hidden from the continue listening section.
+          example: false
+        lastUpdate:
+          $ref: '../schemas.yaml#/components/schemas/updatedAt'
+        startedAt:
+          $ref: '../schemas.yaml#/components/schemas/createdAt'
+        finishedAt:
+          type: integer
+          description: The time (in ms since POSIX epoch) when the media was finished. Will be null if the media has is not finished.
+          example: 1616239000

docs/objects/Permissions.yaml

@@ -0,0 +1,55 @@
+components:
+  schemas:
+    download:
+      type: boolean
+      description: Whether the user has permission to download media.
+      example: true
+    update:
+      type: boolean
+      description: Whether the user has permission to update media.
+      example: true
+    delete:
+      type: boolean
+      description: Whether the user has permission to delete media.
+      example: true
+    upload:
+      type: boolean
+      description: Whether the user has permission to upload media.
+      example: true
+    accessAllLibraries:
+      type: boolean
+      description: Whether the user has permission to access all libraries.
+      example: true
+    accessAllTags:
+      type: boolean
+      description: Whether the user has permission to access all tags.
+      example: true
+    accessExplicitContent:
+      type: boolean
+      description: Whether the user has permission to access explicit content.
+      example: true
+    permissions:
+      type: object
+      properties:
+        download:
+          $ref: '#/components/schemas/download'
+        update:
+          $ref: '#/components/schemas/update'
+        delete:
+          $ref: '#/components/schemas/delete'
+        upload:
+          $ref: '#/components/schemas/upload'
+        accessAllLibraries:
+          $ref: '#/components/schemas/accessAllLibraries'
+        accessAllTags:
+          $ref: '#/components/schemas/accessAllTags'
+        accessExplicitContent:
+          $ref: '#/components/schemas/accessExplicitContent'
+      required:
+        - download
+        - update
+        - delete
+        - upload
+        - accessAllLibraries
+        - accessAllTags
+        - accessExplicitContent

docs/objects/entities/User.yaml

@@ -0,0 +1,85 @@
+components:
+  schemas:
+    username:
+      type: string
+      description: The username to log in with.
+      example: testuser
+    password:
+      type: string
+      description: The password of the user.
+      example: password
+    userId:
+      type: string
+      description: The ID of the user.
+      example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
+      format: uuid
+    userType:
+      type: string
+      description: The type of the user.
+      example: root
+    token:
+      type: string
+      description: The token of the user.
+      example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InRlc3R1c2VyIiwiaWF0IjoxNTE2MjM5MDIyfQ.4k1jJ9
+    socketId:
+      type: string
+      description: The socket ID of the user.
+      example: AFcTcb7xBLsSPnIzAAAV
+    isActive:
+      type: boolean
+      description: Whether the user is active.
+      example: true
+    isLocked:
+      type: boolean
+      description: Whether the user is locked.
+      example: false
+    lastSeen:
+      type: integer
+      description: The time (in ms since POSIX epoch) when the user was last seen.
+      example: 1616239000
+    user:
+      type: object
+      description: A user object which includes the user's ID, username, type, token, and media progress.
+      properties:
+        id:
+          $ref: '#/components/schemas/userId'
+        username:
+          $ref: '#/components/schemas/username'
+        type:
+          $ref: '#/components/schemas/userType'
+        token:
+          $ref: '#/components/schemas/token'
+        mediaProgress:
+          description: The user's progress of media.
+          type: array
+          items:
+            $ref: '../Media.yaml#/components/schemas/mediaProgress'
+        seriesHideFromContinueListening:
+          description: The IDs of series to hide from the user's "Continue Series" shelf.
+          type: array
+          items:
+            $ref: '../LibraryItem.yaml#/components/schemas/libraryItemId'
+        bookmarks:
+          description: The user's bookmarks.
+          type: array
+          items:
+            $ref: '../Bookmarks.yaml#/components/schemas/bookmark'
+        lastSeen:
+          $ref: '#/components/schemas/lastSeen'
+        isActive:
+          $ref: '#/components/schemas/isActive'
+        isLocked:
+          $ref: '#/components/schemas/isLocked'
+        createdAt:
+          $ref: '../../schemas.yaml#/components/schemas/createdAt'
+        permissions:
+          $ref: '../Permissions.yaml#/components/schemas/permissions'
+        librariesAccessible:
+          description: The IDs of libraries the user has access to.
+          type: array
+          items:
+            $ref: '../Library.yaml#/components/schemas/libraryId'
+        itemTagsSelected:
+          $ref: '../../schemas.yaml#/components/schemas/tags'
+
+

docs/objects/mediaTypes/Book.yaml

@@ -9,6 +9,8 @@ components:
       type: object
       description: Base book schema
       properties:
+        id:
+          description: TODO
         libraryItemId:
           $ref: '../LibraryItem.yaml#/components/schemas/libraryItemId'
         coverPath:
@@ -68,3 +70,11 @@ components:
           description: The format of ebook of the book. Will be null if the book is an audiobook.
           type: string
           nullable: true
+    book:
+      allOf:
+        - $ref: '#/components/schemas/bookBase'
+        - type: object
+          properties:
+            metadata:
+              $ref: '../metadata/BookMetadata.yaml#/components/schemas/bookMetadata'
+

docs/objects/metadata/BookMetadata.yaml

@@ -124,3 +124,17 @@ components:
           description: The title of the chapter.
           type: string
           example: Wizards First Rule 01 Chapter 1
+    bookMetadata:
+      allOf:
+        - $ref: '#/components/schemas/bookMetadataBase'
+        - type: object
+          properties:
+            authors:
+              type: array
+              items:
+                $ref: '../entities/Author.yaml#/components/schemas/author'
+            series:
+              type: array
+              items:
+                $ref: '../entities/Series.yaml#/components/schemas/series'
+

docs/root.yaml

@@ -77,6 +77,12 @@ paths:
     $ref: './controllers/PodcastController.yaml#/paths/~1api~1podcasts~1{id}~1episode~1{episodeId}'
   /api/series/{id}:
     $ref: './controllers/SeriesController.yaml#/paths/~1api~1series~1{id}'
+  /login:
+    $ref: './controllers/AuthController.yaml#/paths/~1login'
+  /logout:
+    $ref: './controllers/AuthController.yaml#/paths/~1logout'
+  /api/items/{id}:
+    $ref: './controllers/LibraryItemController.yaml#/paths/~1api~1items~1{id}'
 tags:
   - name: Authors
     description: Author endpoints