Initial library endpoints (#3012)

* Fix: extra type in `Author.yaml`

* Fix: formatting

* Initial library schema

* Additional debugging

* Fix: spec relative paths

* Add: ebook file spec

* Fix: response type should be string

* Linting updates

* Add: missing librarySettings

* Temporary fix: Library cron can be null or false

* Author controller updates

* Add: `/api/libraries/{id}` endpoint

* Update library responses

* Add: descriptions

* Fix: queries should be in body

* Fix: `body` should be `requestBody`

* Move: `libraryController` paths, clean up `requestBody`

* Clean up libraryController parameters

* Move: author endpoints to controller

* Add `get` for author images

* Simplify author schema with items

* Remove: unused response type

* Update: formatting

* Update json

* Update requestBody on LibraryController

* LibrarySettings update

* Replace: generic parameter with path specific parameter

* Fix: requestBody descriptions

* Fix: match post operation

* Temporary: nullable Author schemas

* LibraryController items endpoint

* Add: delete library items with issues

* Massive cleanup and violation fixing

* Update bundled spec

* Add: remove library items with issues

* Add: library items endpoint

* Fix: errors

* Fix: base schemas

* Add: series schemas

* Add: library series endpoint

* Fix: oneOf and array issues

* Add: author search region for matching

* Add: series endpoints

* Fix: series issues

* Add library series endpoint and update deprecation

* Fix: series endpoint deprecation

* Fix: `name` in `sortDesc` schema

* Add: workflow for linting spec

* Update OpenAPI readme

docs/objects/Library.yaml

@@ -3,10 +3,96 @@ components:
     oldLibraryId:
       type: string
       description: The ID of the libraries created on server version 2.2.23 and before.
-      format: "lib_[a-z0-9]{18}"
-      example: lib_o78uaoeuh78h6aoeif
+      format: 'lib_[a-z0-9]{18}'
+      example: 'lib_o78uaoeuh78h6aoeif'
     libraryId:
       type: string
       description: The ID of the library.
       format: uuid
-      example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
+      example: 'e4bb1afb-4a4f-4dd6-8be0-e615d233185b'
+    libraryName:
+      description: The name of the library.
+      type: string
+      example: My Audiobooks
+    librarySettings:
+      description: The settings for the library.
+      type: object
+      properties:
+        coverAspectRatio:
+          description: Whether the library should use square book covers. Must be 0 (for false) or 1 (for true).
+          type: integer
+          example: 1
+        disableWatcher:
+          description: Whether to disable the folder watcher for the library.
+          type: boolean
+          example: false
+        skipMatchingMediaWithAsin:
+          description: Whether to skip matching books that already have an ASIN.
+          type: boolean
+          example: false
+        skipMatchingMediaWithIsbn:
+          description: Whether to skip matching books that already have an ISBN.
+          type: boolean
+          example: false
+        autoScanCronExpression:
+          description: The cron expression for when to automatically scan the library folders. If null, automatic scanning will be disabled.
+          type: string
+          nullable: true
+          example: '0 0 0 * * *'
+        audiobooksOnly:
+          description: Whether the library should ignore ebook files and only allow ebook files to be supplementary.
+          type: boolean
+          example: false
+        hideSingleBookSeries:
+          description: Whether to hide series with only one book.
+          type: boolean
+          example: false
+        onlyShowLaterBooksInContinueSeries:
+          description: Whether to only show books in a series after the highest series sequence.
+          type: boolean
+          example: false
+        metadataPrecedence:
+          description: The precedence of metadata sources. See Metadata Providers for a list of possible providers.
+          type: array
+          items:
+            type: string
+          example: ['folderStructure', 'audioMetatags', 'nfoFile', 'txtFiles', 'opfFile', 'absMetadata']
+        podcastSearchRegion:
+          description: The region to use when searching for podcasts.
+          type: string
+          example: 'us'
+    library:
+      description: A library object which includes either books or podcasts.
+      type: object
+      properties:
+        id:
+          $ref: '#/components/schemas/libraryId'
+        name:
+          $ref: '#/components/schemas/libraryName'
+        folders:
+          description: The folders that belong to the library.
+          type: array
+          items:
+            $ref: './Folder.yaml#/components/schemas/folder'
+        displayOrder:
+          description: Display position of the library in the list of libraries. Must be >= 1.
+          type: integer
+          example: 1
+        icon:
+          description: The selected icon for the library. See Library Icons for a list of possible icons.
+          type: string
+          example: 'audiobookshelf'
+        mediaType:
+          description: The type of media that the library contains. Will be `book` or `podcast`. (Read Only)
+          type: string
+          example: 'book'
+        provider:
+          description: Preferred metadata provider for the library. See Metadata Providers for a list of possible providers.
+          type: string
+          example: 'audible'
+        settings:
+          $ref: '#/components/schemas/librarySettings'
+        createdAt:
+          $ref: '../schemas.yaml#/components/schemas/createdAt'
+        lastUpdate:
+          $ref: '../schemas.yaml#/components/schemas/updatedAt'

docs/objects/LibraryItem.yaml

@@ -4,7 +4,7 @@ components:
       description: The ID of library items on server version 2.2.23 and before.
       type: string
       nullable: true
-      format: "li_[a-z0-9]{18}"
+      format: 'li_[a-z0-9]{18}'
       example: li_o78uaoeuh78h6aoeif
     libraryItemId:
       type: string
@@ -59,8 +59,14 @@ components:
       type: object
       description: A single item on the server, like a book or podcast. Minified media format.
       allOf:
-        - $ref : '#/components/schemas/libraryItemBase'
+        - $ref: '#/components/schemas/libraryItemBase'
         - type: object
           properties:
             media:
               $ref: './mediaTypes/media.yaml#/components/schemas/mediaMinified'
+    libraryItemSequence:
+      type: object
+      description: A single item on the server, like a book or podcast. Includes series sequence information.
+      allOf:
+        - $ref: '#/components/schemas/libraryItemBase'
+        - $ref: './entities/Series.yaml#/components/schemas/sequence'

docs/objects/entities/Author.yaml

@@ -6,14 +6,24 @@ components:
       format: uuid
       example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
     authorAsin:
-      type: string
       description: The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.
+      type: string
       nullable: true
       example: B000APZOQA
     authorName:
       description: The name of the author.
       type: string
       example: Terry Goodkind
+    authorDescription:
+      description: The new description of the author.
+      type: string
+      nullable: true
+      example: Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork, ‘The Sword of Truth’. He has written 30+ major, bestselling novels, has been published in more than 20 languages world-wide, and has sold more than 26 Million books. ‘The Sword of Truth’ is a revered literary tour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing.
+    authorImagePath:
+      description: The absolute path for the author image. This will be in the `metadata/` directory. Will be null if there is no image.
+      type: string
+      nullable: true
+      example: /metadata/authors/aut_z3leimgybl7uf3y4ab.jpg
     authorSeries:
       type: object
       description: Series and the included library items that an author has written.
@@ -26,9 +36,9 @@ components:
           description: The items in the series. Each library item's media's metadata will have a `series` attribute, a `Series Sequence`, which is the matching series.
           type: array
           items:
-            ref: '../LibraryItem.yaml#/components/schemas/libraryItemMinified'
+            $ref: '../LibraryItem.yaml#/components/schemas/libraryItemMinified'
     author:
-      description: An author object which includes a description and image path.
+      description: An author object which includes a description and image path. The library items and series associated with the author are optionally included.
       type: object
       properties:
         id:
@@ -38,51 +48,23 @@ components:
         name:
           $ref: '#/components/schemas/authorName'
         description:
-          description: A description of the author. Will be null if there is none.
-          type: string
-          nullable: true
-          example: |
-            Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork,
-            ‘The Sword of Truth’. He has written 30+ major, bestselling novels, has been published in more than 20
-            languages world-wide, and has sold more than 26 Million books. ‘The Sword of Truth’ is a revered literary
-            tour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. Terry Goodkind's
-            brilliant books are character-driven stories, with a focus on the complexity of the human psyche. Goodkind
-            has an uncanny grasp for crafting compelling stories about people like you and me, trapped in terrifying
-            situations.
+          $ref: '#/components/schemas/authorDescription'
         imagePath:
-          description: The absolute path for the author image located in the `metadata/` directory. Will be null if there is no image.
-          type: string
-          nullable: true
-          example: /metadata/authors/aut_bxxbyjiptmgb56yzoz.jpg
+          $ref: '#/components/schemas/authorImagePath'
         addedAt:
           $ref: '../../schemas.yaml#/components/schemas/addedAt'
         updatedAt:
           $ref: '../../schemas.yaml#/components/schemas/updatedAt'
-    authorWithItems:
-      type: object
-      description: The author schema with an array of items they are associated with.
-      allOf:
-        - $ref: '#/components/schemas/author'
-        - type: object
-          properties:
-            libraryItems:
-              description: The items associated with the author
-              type: string
-              type: array
-              items:
-                $ref: '../LibraryItem.yaml#/components/schemas/libraryItemMinified'
-    authorWithSeries:
-      type: object
-      description: The author schema with an array of items and series they are associated with.
-      allOf:
-        - $ref: '#/components/schemas/authorWithItems'
-        - type: object
-          properties:
-            series:
-              description: The series associated with the author
-              type: array
-              items:
-                $ref: '#/components/schemas/authorSeries'
+        libraryItems:
+          description: The items associated with the author
+          type: array
+          items:
+            $ref: '../LibraryItem.yaml#/components/schemas/libraryItemMinified'
+        series:
+          description: The series associated with the author
+          type: array
+          items:
+            $ref: '#/components/schemas/authorSeries'
     authorMinified:
       type: object
       description: Minified author object which only contains the author name and ID.
@@ -101,4 +83,4 @@ components:
             numBooks:
               description: The number of books associated with the author in the library.
               type: integer
-              example: 1
+              example: 1

docs/objects/entities/Series.yaml

@@ -8,4 +8,110 @@ components:
     seriesName:
       description: The name of the series.
       type: string
-      example: Sword of Truth
+      example: Sword of Truth
+    seriesDescription:
+      description: A description for the series. Will be null if there is none.
+      type: string
+      nullable: true
+      example: The Sword of Truth is a series of twenty one epic fantasy novels written by Terry Goodkind.
+    sequence:
+      description: The position in the series the book is.
+      type: string
+      nullable: true
+    seriesProgress:
+      type: object
+      description: The user's progress of a series.
+      properties:
+        libraryItemIds:
+          description: The IDs of the library items in the series.
+          type: array
+          items:
+            $ref: '../LibraryItem.yaml#/components/schemas/libraryItemId'
+        libraryItemIdsFinished:
+          description: The IDs of the library items in the series that are finished.
+          type: array
+          items:
+            $ref: '../LibraryItem.yaml#/components/schemas/libraryItemId'
+        isFinished:
+          description: Whether the series is finished.
+          type: boolean
+    series:
+      type: object
+      description: A series object which includes the name and description of the series.
+      properties:
+        id:
+          $ref: '#/components/schemas/seriesId'
+        name:
+          $ref: '#/components/schemas/seriesName'
+        description:
+          $ref: '#/components/schemas/seriesDescription'
+        addedAt:
+          $ref: '../../schemas.yaml#/components/schemas/addedAt'
+        updatedAt:
+          $ref: '../../schemas.yaml#/components/schemas/updatedAt'
+    seriesNumBooks:
+      type: object
+      description: A series object which includes the name and number of books in the series.
+      properties:
+        id:
+          $ref: '#/components/schemas/seriesId'
+        name:
+          $ref: '#/components/schemas/seriesName'
+        numBooks:
+          description: The number of books in the series.
+          type: integer
+        libraryItemIds:
+          description: The IDs of the library items in the series.
+          type: array
+          items:
+            $ref: '../LibraryItem.yaml#/components/schemas/libraryItemId'
+    seriesBooks:
+      type: object
+      description: A series object which includes the name and books in the series.
+      properties:
+        id:
+          $ref: '#/components/schemas/seriesId'
+        name:
+          $ref: '#/components/schemas/seriesName'
+        addedAt:
+          $ref: '../../schemas.yaml#/components/schemas/addedAt'
+        nameIgnorePrefix:
+          description: The name of the series with any prefix moved to the end.
+          type: string
+        nameIgnorePrefixSort:
+          description: The name of the series with any prefix removed.
+          type: string
+        type:
+          description: Will always be `series`.
+          type: string
+        books:
+          description: The library items that contain the books in the series. A sequence attribute that denotes the position in the series the book is in, is tacked on.
+          type: array
+          items:
+            $ref: '../LibraryItem.yaml#/components/schemas/libraryItemSequence'
+        totalDuration:
+          description: The combined duration (in seconds) of all books in the series.
+          type: number
+    seriesSequence:
+      type: object
+      description: A series object which includes the name and sequence of the series.
+      properties:
+        id:
+          $ref: '#/components/schemas/seriesId'
+        name:
+          $ref: '#/components/schemas/seriesName'
+        sequence:
+          $ref: '#/components/schemas/sequence'
+    seriesWithProgressAndRSS:
+      type: object
+      description: A series object which includes the name and progress of the series.
+      oneOf:
+        - $ref: '#/components/schemas/series'
+        - type: object
+          properties:
+            progress:
+              $ref: '#/components/schemas/seriesProgress'
+            rssFeed:
+              description: The RSS feed for the series.
+              type: string
+              example: 'TBD'

docs/objects/files/AudioFile.yaml

@@ -52,7 +52,7 @@ components:
           type: string
           example: MP2/3 (MPEG audio layer 2/3)
         duration:
-          $ref: '#/components/schemas/durationSec'
+          $ref: '../../schemas.yaml#/components/schemas/durationSec'
         bitRate:
           description: The bit rate (in bit/s) of the audio file.
           type: integer

docs/objects/files/EBookFile.yaml

@@ -0,0 +1,17 @@
+components:
+  schemas:
+    ebookFile:
+      type: object
+      properties:
+        ino:
+          $ref: '../../schemas.yaml#/components/schemas/inode'
+        metadata:
+          $ref: '../metadata/FileMetadata.yaml#/components/schemas/fileMetadata'
+        ebookFormat:
+          description: The ebook format of the ebook file.
+          type: string
+          example: epub
+        addedAt:
+          $ref: '../../schemas.yaml#/components/schemas/addedAt'
+        updatedAt:
+          $ref: '../../schemas.yaml#/components/schemas/updatedAt'

docs/objects/mediaTypes/Book.yaml

@@ -18,18 +18,18 @@ components:
         audioFiles:
           type: array
           items:
-            $ref: '#/components/schemas/audioFile'
+            $ref: '../files/AudioFile.yaml#/components/schemas/audioFile'
         chapters:
           type: array
           items:
-            $ref: '#/components/schemas/bookChapter'
+            $ref: '../metadata/BookMetadata.yaml#/components/schemas/bookChapter'
         missingParts:
           description: Any parts missing from the book by track index.
           type: array
           items:
             type: integer
         ebookFile:
-          $ref: '#/components/schemas/ebookFile'
+          $ref: '../files/EBookFile.yaml#/components/schemas/ebookFile'
     bookMinified:
       type: object
       description: Minified book schema. Does not depend on `bookBase` because there's pretty much no overlap.