diff --git a/docs/controllers/SeriesController.yaml b/docs/controllers/SeriesController.yaml new file mode 100644 index 000000000..2788ac1b1 --- /dev/null +++ b/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' diff --git a/docs/objects/entities/Series.yaml b/docs/objects/entities/Series.yaml index a1998260d..90c8e04aa 100644 --- a/docs/objects/entities/Series.yaml +++ b/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' diff --git a/docs/openapi.json b/docs/openapi.json index 3b94c9039..baf4259da 100644 --- a/docs/openapi.json +++ b/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." + } + } + } } } } diff --git a/docs/root.yaml b/docs/root.yaml index 61b0d0176..ca42751c3 100644 --- a/docs/root.yaml +++ b/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