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/controllers/AuthorController.yaml

@@ -4,136 +4,291 @@ components:
       description: Whether the author was updated without errors. Will not exist if author was merged.
       type: boolean
       nullable: true
-  parameters:
-    authorId:
-      name: id
-      in: path
-      description: Author ID
-      required: true
-      schema:
-        $ref: '../objects/entities/Author.yaml#/components/schemas/authorId'
+    authorMerged:
+      description: Whether the author was merged with another author. Will not exist if author was updated.
+      type: boolean
+      nullable: true
     authorInclude:
-      name: include
-      in: query
-      description: A comma separated list of what to include with the author. The options are `items` and `series`. `series` will only have an effect if `items` is included.
-      required: false
-      schema:
-        type: string
-        example: "items"
-      examples:
-        empty:
-          summary: Do not return library items
-          value: ""
-        itemOnly:
-          summary: Only return library items
-          value: "items"
-        itemsAndSeries:
-          summary: Return library items and series
-          value: "items,series"
+      description: A comma separated list of what to include with the author. The options are `items` and `series`. `series` will only have an effect if `items` is included. For example, the value `items,series` will include both library items and series.
+      type: string
+      example: 'items'
     authorLibraryId:
-      name: library
-      in: query
-      description: The ID of the library to to include filter included items from.
-      required: false
-      schema:
-        $ref: '../objects/Library.yaml#/components/schemas/libraryId'
-    asin:
-      name: asin
-      in: query
-      description: The Audible Identifier (ASIN).
-      required: false
-      schema:
-        $ref: '../objects/entities/Author.yaml#/components/schemas/authorAsin'
+      $ref: '../objects/Library.yaml#/components/schemas/libraryId'
     authorSearchName:
-      name: q
-      in: query
       description: The name of the author to use for searching.
-      required: false
-      schema:
-        type: string
-        example: Terry Goodkind
+      type: string
+      example: Terry Goodkind
     authorName:
-      name: name
-      in: query
-      description: The new name of the author.
-      required: false
-      schema:
-        $ref: '../objects/entities/Author.yaml#/components/schemas/authorName'
-    authorDescription:
-      name: description
-      in: query
-      description: The new description of the author.
-      required: false
-      schema:
-        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:
-      name: imagePath
-      in: query
-      description: The new absolute path for the author image.
-      required: false
-      schema:
-        type: string
-        nullable: true
-        example: /metadata/authors/aut_z3leimgybl7uf3y4ab.jpg
+      $ref: '../objects/entities/Author.yaml#/components/schemas/authorName'
     imageUrl:
-      name: url
-      in: query
       description: The URL of the image to add to the server
-      required: true
-      schema:
-        type: string
-        format: uri
-        example: https://images-na.ssl-images-amazon.com/images/I/51NoQTm33OL.__01_SX120_CR0,0,120,120__.jpg
+      type: string
+      format: uri
+      example: https://images-na.ssl-images-amazon.com/images/I/51NoQTm33OL.__01_SX120_CR0,0,120,120__.jpg
     imageWidth:
-      name: width
-      in: query
       description: The requested width of image in pixels.
-      schema:
-        type: integer
-        default: 400
-        example: 400
+      type: integer
+      default: 400
       example: 400
     imageHeight:
-      name: height
-      in: query
       description: The requested height of image in pixels. If `null`, the height is scaled to maintain aspect ratio based on the requested width.
-      schema:
-        type: integer
-        nullable: true
-        default: null
-        example: 600
-      examples:
-        scaleHeight:
-          summary: Scale height with width
-          value: null
-        fixedHeight:
-          summary: Force height of image
-          value: 600
+      type: integer
+      nullable: true
+      default: null
+      example: 600
     imageFormat:
-      name: format
-      in: query
       description: The requested output format.
-      schema:
-        type: string
-        default: jpeg
-        example: webp
+      type: string
+      default: jpeg
+      example: webp
     imageRaw:
-      name: raw
-      in: query
       description: Return the raw image without scaling if true.
-      schema:
-        type: boolean
-        default: false
-  responses: 
+      type: boolean
+      default: false
+  responses:
+    author200:
+      description: Author found.
+      content:
+        application/json:
+          schema:
+            $ref: '../objects/entities/Author.yaml#/components/schemas/author'
     author404:
       description: Author not found.
       content:
         text/html:
           schema:
             type: string
-            example: Not found
-tags:
-  - name: Authors
-    description: Author endpoints
+            example: Author not found.
+paths:
+  /api/authors/{id}:
+    parameters:
+      - name: id
+        in: path
+        description: Author ID
+        required: true
+        schema:
+          $ref: '../objects/entities/Author.yaml#/components/schemas/authorId'
+    get:
+      operationId: getAuthorById
+      summary: Get an author by ID
+      description: Get an author by ID. The author's books and series can be included in the response.
+      tags:
+        - Authors
+      requestBody:
+        required: false
+        description: The author object to create.
+        content:
+          application/json:
+            schema:
+              properties:
+                include:
+                  $ref: '#/components/schemas/authorInclude'
+                library:
+                  $ref: '#/components/schemas/authorLibraryId'
+      responses:
+        '200':
+          description: getAuthorById OK
+          content:
+            application/json:
+              schema:
+                $ref: '../objects/entities/Author.yaml#/components/schemas/author'
+        '404':
+          $ref: '#/components/responses/author404'
+    patch:
+      operationId: updateAuthorById
+      summary: Update an author by ID
+      description: Update an author by ID. The author's name and description can be updated. This endpoint will merge two authors if the new author name matches another author name in the database.
+      tags:
+        - Authors
+      requestBody:
+        description: The author object to update.
+        content:
+          application/json:
+            schema:
+              properties:
+                name:
+                  $ref: '#/components/schemas/authorName'
+                description:
+                  $ref: '../objects/entities/Author.yaml#/components/schemas/authorDescription'
+                imagePath:
+                  $ref: '../objects/entities/Author.yaml#/components/schemas/authorImagePath'
+                asin:
+                  $ref: '../objects/entities/Author.yaml#/components/schemas/authorAsin'
+      responses:
+        '200':
+          description: updateAuthorById OK
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '../objects/entities/Author.yaml#/components/schemas/author'
+                  - $ref: '#/components/schemas/authorUpdated'
+                  - $ref: '#/components/schemas/authorMerged'
+        '404':
+          $ref: '#/components/responses/author404'
+    delete:
+      operationId: deleteAuthorById
+      summary: Delete an author by ID
+      description: Delete an author by ID. This will remove the author from all books.
+      tags:
+        - Authors
+      responses:
+        '200':
+          description: deleteAuthorById OK
+          content:
+            text/plain:
+              schema:
+                type: string
+                example: Author deleted.
+        '404':
+          $ref: '#/components/responses/author404'
+  /api/authors/{id}/image:
+    parameters:
+      - name: id
+        in: path
+        description: Author ID
+        required: true
+        schema:
+          $ref: '../objects/entities/Author.yaml#/components/schemas/authorId'
+    get:
+      operationId: getAuthorImageById
+      summary: Get an author image by author ID
+      description: Get an author image by author ID. The image will be returned in the requested format and size.
+      tags:
+        - Authors
+      requestBody:
+        required: false
+        description: The author image to get.
+        content:
+          application/json:
+            schema:
+              properties:
+                width:
+                  $ref: '#/components/schemas/imageWidth'
+                height:
+                  $ref: '#/components/schemas/imageHeight'
+                format:
+                  $ref: '#/components/schemas/imageFormat'
+                raw:
+                  $ref: '#/components/schemas/imageRaw'
+      responses:
+        '200':
+          description: getAuthorImageById OK
+          content:
+            image/webp:
+              schema:
+                type: string
+                format: binary
+            image/jpeg:
+              schema:
+                type: string
+                format: binary
+            image/*:
+              schema:
+                type: string
+                format: binary
+        '404':
+          $ref: '#/components/responses/author404'
+    post:
+      operationId: addAuthorImageById
+      summary: Add an author image to the server
+      description: Add an author image to the server. The image will be downloaded from the provided URL and stored on the server.
+      tags:
+        - Authors
+      requestBody:
+        required: true
+        description: The author image to add by URL.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/imageUrl'
+      responses:
+        '200':
+          description: addAuthorImageById OK
+          content:
+            image/*:
+              schema:
+                type: string
+                format: binary
+        '404':
+          $ref: '#/components/responses/author404'
+    patch:
+      operationId: updateAuthorImageById
+      summary: Update an author image by author ID
+      description: Update an author image by author ID. The image will be resized if the width, height, or format is provided.
+      tags:
+        - Authors
+      requestBody:
+        description: The author image to update.
+        content:
+          application/json:
+            schema:
+              properties:
+                width:
+                  $ref: '#/components/schemas/imageWidth'
+                height:
+                  $ref: '#/components/schemas/imageHeight'
+                format:
+                  $ref: '#/components/schemas/imageFormat'
+                raw:
+                  $ref: '#/components/schemas/imageRaw'
+      responses:
+        '200':
+          description: updateAuthorImageById OK
+          content:
+            image/*:
+              schema:
+                type: string
+                format: binary
+        '404':
+          $ref: '#/components/responses/author404'
+    delete:
+      operationId: deleteAuthorImageById
+      summary: Delete an author image by author ID
+      description: Delete an author image by author ID. This will remove the image from the server and the database.
+      tags:
+        - Authors
+      responses:
+        '200':
+          description: deleteAuthorImageById OK
+        '404':
+          $ref: '#/components/responses/author404'
+  /api/authors/{id}/match:
+    parameters:
+      - name: id
+        in: path
+        description: Author ID
+        required: true
+        schema:
+          $ref: '../objects/entities/Author.yaml#/components/schemas/authorId'
+    post:
+      operationId: matchAuthorById
+      summary: Match the author against Audible using quick match
+      description: Match the author against Audible using quick match. Quick match updates the author's description and image (if no image already existed) with information from audible. Either `asin` or `q` must be provided, with `asin` taking priority if both are provided.
+      tags:
+        - Authors
+      requestBody:
+        required: true
+        description: The author object to match against an online provider.
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                q:
+                  $ref: '#/components/schemas/authorSearchName'
+                asin:
+                  $ref: '../objects/entities/Author.yaml#/components/schemas/authorAsin'
+                region:
+                  $ref: '../schemas.yaml#/components/schemas/region'
+      responses:
+        '200':
+          description: matchAuthorById OK
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '../objects/entities/Author.yaml#/components/schemas/author'
+                  - $ref: '#/components/schemas/authorUpdated'
+        '404':
+          $ref: '#/components/responses/author404'

docs/controllers/LibraryController.yaml

@@ -0,0 +1,435 @@
+components:
+  schemas:
+    sortBy:
+      type: string
+      description: The field to sort by from the request.
+      example: 'media.metadata.title'
+    sortDesc:
+      description: Whether to sort in descending order.
+      type: boolean
+      example: true
+    filterBy:
+      type: string
+      description: The field to filter by from the request. TODO
+      example: 'media.metadata.title'
+    collapseSeries:
+      type: boolean
+      description: Whether collapse series was set in the request.
+      example: true
+    libraryFolders:
+      description: The folders of the library. Only specify the fullPath.
+      type: array
+      items:
+        $ref: '../objects/Folder.yaml#/components/schemas/folder'
+    libraryDisplayOrder:
+      description: The display order of the library. Must be >= 1.
+      type: integer
+      minimum: 1
+      example: 1
+    libraryIcon:
+      description: The icon of the library. See Library Icons for a list of possible icons.
+      type: string
+      example: 'audiobookshelf'
+    libraryMediaType:
+      description: The type of media that the library contains. Must be `book` or `podcast`.
+      type: string
+      example: 'book'
+    libraryProvider:
+      description: Preferred metadata provider for the library. See Metadata Providers for a list of possible providers.
+      type: string
+      example: 'audible'
+    librarySettings:
+      $ref: '../objects/Library.yaml#/components/schemas/librarySettings'
+    librarySort:
+      description: The sort order of the library. For example, to sort by title use 'sort=media.metadata.title'.
+      type: string
+      example: 'media.metadata.title'
+    libraryFilter:
+      description: The filter for the library.
+      type: string
+      example: 'media.metadata.title'
+    libraryCollapseSeries:
+      description: Whether to collapse series.
+      type: boolean
+      example: true
+      default: false
+    libraryInclude:
+      description: The fields to include in the response. The only current option is `rssfeed`.
+      type: string
+      example: 'rssfeed'
+  responses:
+    library200:
+      description: Library found.
+      content:
+        application/json:
+          schema:
+            $ref: '../objects/Library.yaml#/components/schemas/library'
+    library404:
+      description: Library not found.
+      content:
+        text/html:
+          schema:
+            type: string
+            example: Library not found.
+paths:
+  /api/libraries:
+    get:
+      operationId: getLibraries
+      summary: Get all libraries on server
+      description: Get all libraries on server.
+      tags:
+        - Libraries
+      responses:
+        '200':
+          description: getLibraries OK
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '../objects/Library.yaml#/components/schemas/library'
+    post:
+      operationId: createLibrary
+      summary: Create a new library on server
+      description: Create a new library on server.
+      tags:
+        - Libraries
+      requestBody:
+        description: The library object to create.
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [name, folders]
+              properties:
+                name:
+                  $ref: '../objects/Library.yaml#/components/schemas/libraryName'
+                folders:
+                  $ref: '#/components/schemas/libraryFolders'
+                displayOrder:
+                  $ref: '#/components/schemas/libraryDisplayOrder'
+                icon:
+                  $ref: '#/components/schemas/libraryIcon'
+                mediaType:
+                  $ref: '#/components/schemas/libraryMediaType'
+                provider:
+                  $ref: '#/components/schemas/libraryProvider'
+                settings:
+                  $ref: '#/components/schemas/librarySettings'
+      responses:
+        '200':
+          $ref: '#/components/responses/library200'
+        '404':
+          $ref: '#/components/responses/library404'
+  /api/libraries/{id}:
+    parameters:
+      - name: id
+        in: path
+        description: The ID of the library.
+        required: true
+        schema:
+          $ref: '../objects/Library.yaml#/components/schemas/libraryId'
+    get:
+      operationId: getLibraryById
+      summary: Get a single library by ID on server
+      description: Get a single library by ID on server.
+      tags:
+        - Libraries
+      responses:
+        '200':
+          $ref: '#/components/responses/library200'
+        '404':
+          $ref: '#/components/responses/library404'
+    patch:
+      operationId: updateLibraryById
+      summary: Update a single library by ID on server
+      description: Update a single library by ID on server.
+      tags:
+        - Libraries
+      requestBody:
+        required: true
+        description: The library object to update.
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  $ref: '../objects/Library.yaml#/components/schemas/libraryName'
+                folders:
+                  $ref: '#/components/schemas/libraryFolders'
+                displayOrder:
+                  $ref: '#/components/schemas/libraryDisplayOrder'
+                icon:
+                  $ref: '#/components/schemas/libraryIcon'
+                mediaType:
+                  $ref: '#/components/schemas/libraryMediaType'
+                provider:
+                  $ref: '#/components/schemas/libraryProvider'
+                settings:
+                  $ref: '#/components/schemas/librarySettings'
+      responses:
+        '200':
+          $ref: '#/components/responses/library200'
+        '404':
+          $ref: '#/components/responses/library404'
+    delete:
+      operationId: deleteLibraryById
+      summary: Delete a single library by ID on server
+      description: Delete a single library by ID on server and return the deleted object.
+      tags:
+        - Libraries
+      responses:
+        '200':
+          $ref: '#/components/responses/library200'
+        '404':
+          $ref: '#/components/responses/library404'
+  /api/libraries/{id}/issues:
+    parameters:
+      - name: id
+        in: path
+        description: The ID of the library.
+        required: true
+        schema:
+          $ref: '../objects/Library.yaml#/components/schemas/libraryId'
+    delete:
+      operationId: deleteLibraryIssues
+      summary: Delete items with issues in a library.
+      description: Delete all items with issues in a library by library ID on the server. This only removes the items from the ABS database and does not delete media files.
+      tags:
+        - Libraries
+      responses:
+        '200':
+          description: deleteLibraryIssues OK
+          content:
+            application/json:
+              schema:
+                type: string
+                example: 'Issues deleted.'
+        '404':
+          $ref: '#/components/responses/library404'
+  /api/libraries/{id}/items:
+    parameters:
+      - name: id
+        in: path
+        description: The ID of the library.
+        required: true
+        schema:
+          $ref: '../objects/Library.yaml#/components/schemas/libraryId'
+    get:
+      operationId: getLibraryItems
+      summary: Get items in a library
+      description: Get items in a library by ID on server.
+      tags:
+        - Libraries
+      requestBody:
+        required: false
+        description: The filters to apply to the requested library items.
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                limit:
+                  $ref: '../schemas.yaml#/components/schemas/limit'
+                page:
+                  $ref: '../schemas.yaml#/components/schemas/page'
+                sort:
+                  $ref: '#/components/schemas/librarySort'
+                desc:
+                  $ref: '../schemas.yaml#/components/schemas/sortDesc'
+                filter:
+                  $ref: '#/components/schemas/libraryFilter'
+                minified:
+                  $ref: '../schemas.yaml#/components/schemas/minified'
+                collapseSeries:
+                  $ref: '#/components/schemas/libraryCollapseSeries'
+                include:
+                  $ref: '#/components/schemas/libraryInclude'
+      responses:
+        '200':
+          description: getLibraryItems OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  results:
+                    type: array
+                    items:
+                      $ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItemBase'
+                  total:
+                    $ref: '../schemas.yaml#/components/schemas/total'
+                  limit:
+                    $ref: '../schemas.yaml#/components/schemas/limit'
+                  page:
+                    $ref: '../schemas.yaml#/components/schemas/page'
+                  sortBy:
+                    $ref: '#/components/schemas/sortBy'
+                  sortDesc:
+                    $ref: '#/components/schemas/sortDesc'
+                  filterBy:
+                    $ref: '#/components/schemas/filterBy'
+                  mediaType:
+                    $ref: '../objects/mediaTypes/media.yaml#/components/schemas/mediaType'
+                  minified:
+                    $ref: '../schemas.yaml#/components/schemas/minified'
+                  collapseSeries:
+                    $ref: '#/components/schemas/collapseSeries'
+                  include:
+                    $ref: '#/components/schemas/libraryInclude'
+        '404':
+          $ref: '#/components/responses/library404'
+  /api/libraries/{id}/authors:
+    parameters:
+      - name: id
+        in: path
+        description: The ID of the library.
+        required: true
+        schema:
+          $ref: '../objects/Library.yaml#/components/schemas/libraryId'
+    get:
+      operationId: getLibraryAuthors
+      summary: Get all authors in a library
+      description: Get all authors in a library by ID on server.
+      tags:
+        - Libraries
+      responses:
+        '200':
+          description: getLibraryAuthors OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  authors:
+                    type: array
+                    items:
+                      $ref: '../objects/entities/Author.yaml#/components/schemas/authorExpanded'
+        '404':
+          $ref: '#/components/responses/library404'
+  /api/libraries/{id}/series:
+    parameters:
+      - name: id
+        in: path
+        description: The ID of the library.
+        required: true
+        schema:
+          $ref: '../objects/Library.yaml#/components/schemas/libraryId'
+    get:
+      operationId: getLibrarySeries
+      summary: Get library series
+      description: Get series in a library. Filtering and sorting can be applied.
+      tags:
+        - Libraries
+      requestBody:
+        required: false
+        description: The filters to apply to the requested library series.
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                limit:
+                  $ref: '../schemas.yaml#/components/schemas/limit'
+                page:
+                  $ref: '../schemas.yaml#/components/schemas/page'
+                sort:
+                  description: The field to sort by from the request.
+                  type: string
+                  enum: ['name', 'numBooks', 'totalDuration', 'addedAt', 'lastBookAdded', 'lastBookUpdated']
+                  example: 'numBooks'
+                  default: 'name'
+                desc:
+                  $ref: '../schemas.yaml#/components/schemas/sortDesc'
+                filter:
+                  $ref: '#/components/schemas/libraryFilter'
+                include:
+                  $ref: '#/components/schemas/libraryInclude'
+      responses:
+        '200':
+          description: getLibrarySeries OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  results:
+                    type: array
+                    items:
+                      $ref: '../objects/entities/Series.yaml#/components/schemas/seriesBooks'
+                  total:
+                    $ref: '../schemas.yaml#/components/schemas/total'
+                  limit:
+                    $ref: '../schemas.yaml#/components/schemas/limit'
+                  page:
+                    $ref: '../schemas.yaml#/components/schemas/page'
+                  sortBy:
+                    $ref: '#/components/schemas/sortBy'
+                  sortDesc:
+                    $ref: '#/components/schemas/sortDesc'
+                  filterBy:
+                    $ref: '#/components/schemas/filterBy'
+                  minified:
+                    $ref: '../schemas.yaml#/components/schemas/minified'
+                  include:
+                    $ref: '#/components/schemas/libraryInclude'
+
+        '404':
+          $ref: '#/components/responses/library404'
+  /api/libraries/{id}/series/{seriesId}:
+    parameters:
+      - name: id
+        in: path
+        description: The ID of the library.
+        required: true
+        schema:
+          $ref: '../objects/Library.yaml#/components/schemas/libraryId'
+      - name: seriesId
+        in: path
+        description: The ID of the series.
+        required: true
+        schema:
+          $ref: '../objects/entities/Series.yaml#/components/schemas/seriesId'
+    get:
+      operationId: getLibrarySeriesById
+      summary: Get single series in library
+      description: Get a single series in a library by ID on server. This endpoint is deprecated and `/api/series/{id}` should be used instead.
+      deprecated: true
+      tags:
+        - Libraries
+      requestBody:
+        required: false
+        description: The filters to apply to the requested library series.
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                limit:
+                  $ref: '../schemas.yaml#/components/schemas/limit'
+                page:
+                  $ref: '../schemas.yaml#/components/schemas/page'
+                sort:
+                  description: The field to sort by from the request.
+                  type: string
+                  enum: ['name', 'numBooks', 'totalDuration', 'addedAt', 'lastBookAdded', 'lastBookUpdated']
+                  example: 'numBooks'
+                  default: 'name'
+                desc:
+                  $ref: '../schemas.yaml#/components/schemas/sortDesc'
+                filter:
+                  $ref: '#/components/schemas/libraryFilter'
+                minified:
+                  $ref: '../schemas.yaml#/components/schemas/minified'
+                include:
+                  $ref: '#/components/schemas/libraryInclude'
+      responses:
+        '200':
+          description: getLibrarySeriesById OK
+          content:
+            application/json:
+              schema:
+                $ref: '../objects/entities/Series.yaml#/components/schemas/seriesWithProgressAndRSS'
+        '404':
+          $ref: '#/components/responses/library404'

docs/controllers/SeriesController.yaml

@@ -0,0 +1,72 @@
+components:
+  responses:
+    series404:
+      description: Series not found.
+      content:
+        text/html:
+          schema:
+            type: string
+            example: Series not found.
+paths:
+  /api/series/{id}:
+    parameters:
+      - name: id
+        in: path
+        description: The ID of the series.
+        required: true
+        schema:
+          $ref: '../objects/entities/Series.yaml#/components/schemas/seriesId'
+    get:
+      operationId: getSeries
+      tags:
+        - Series
+      summary: Get series
+      description: Get a series by ID.
+      requestBody:
+        required: false
+        description: A comma separated list of what to include with the series.
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                include:
+                  type: string
+                  description: A comma separated list of what to include with the series.
+                  example: 'progress,rssfeed'
+                  enum: ['progress', 'rssfeed', 'progress,rssfeed', 'rssfeed,progress']
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '../objects/entities/Series.yaml#/components/schemas/seriesWithProgressAndRSS'
+        '404':
+          $ref: '#/components/responses/series404'
+    patch:
+      operationId: updateSeries
+      tags:
+        - Series
+      summary: Update series
+      description: Update a series by ID.
+      requestBody:
+        required: true
+        description: The series to update.
+        content:
+          application/json:
+            schema:
+              properties:
+                name:
+                  $ref: '../objects/entities/Series.yaml#/components/schemas/seriesName'
+                description:
+                  $ref: '../objects/entities/Series.yaml#/components/schemas/seriesDescription'
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '../objects/entities/Series.yaml#/components/schemas/series'
+        '404':
+          $ref: '#/components/responses/series404'