Add: series endpoints

docs/controllers/SeriesController.yaml

@@ -0,0 +1,70 @@
+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:
+      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']
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '../objects/entities/Series.yaml#/components/schemas/seriesWithProgressAndRSS'
+        '404':
+          $ref: '#/components/responses/series404'
+    patch:
+      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'

docs/objects/entities/Series.yaml

@@ -18,6 +18,23 @@ components:
       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.
@@ -85,3 +102,17 @@ components:
           $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.
+      properties:
+        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/openapi.json

@@ -871,6 +871,103 @@
           }
         }
       }
+    },
+    "/api/series/{id}": {
+      "parameters": [
+        {
+          "name": "id",
+          "in": "path",
+          "description": "The ID of the series.",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/seriesId"
+          }
+        }
+      ],
+      "get": {
+        "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"
+                    ]
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/seriesWithProgressAndRSS"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/series404"
+          }
+        }
+      },
+      "patch": {
+        "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": "#/components/schemas/seriesName"
+                  },
+                  "description": {
+                    "$ref": "#/components/schemas/seriesDescription"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/series"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/series404"
+          }
+        }
+      }
     }
   },
   "components": {
@@ -1674,6 +1771,57 @@
             "type": "number"
           }
         }
+      },
+      "seriesWithProgressAndRSS": {
+        "type": "object",
+        "description": "A series object which includes the name and progress of the series.",
+        "properties": {
+          "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"
+                }
+              }
+            }
+          ]
+        }
+      },
+      "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."
+      },
+      "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": "#/components/schemas/addedAt"
+          },
+          "updatedAt": {
+            "$ref": "#/components/schemas/updatedAt"
+          }
+        }
       }
     },
     "responses": {
@@ -1708,6 +1856,17 @@
             }
           }
         }
+      },
+      "series404": {
+        "description": "Series not found.",
+        "content": {
+          "text/html": {
+            "schema": {
+              "type": "string",
+              "example": "Series not found."
+            }
+          }
+        }
       }
     }
   }

docs/root.yaml

@@ -33,6 +33,8 @@ paths:
     $ref: './controllers/LibraryController.yaml#/paths/~1api~1libraries~1{id}~1issues'
   /api/libraries/{id}/series:
     $ref: './controllers/LibraryController.yaml#/paths/~1api~1libraries~1{id}~1series'
+  /api/series/{id}:
+    $ref: './controllers/SeriesController.yaml#/paths/~1api~1series~1{id}'
 tags:
   - name: Authors
     description: Author endpoints