Mirrors/audiobookshelf
Mirrors/audiobookshelf
1
0
Fork 0
mirror of https://github.com/advplyr/audiobookshelf.git synced 2024-12-20 19:06:06 +01:00
Code Issues Packages Projects Releases Wiki Activity

Update library series endpoint openapi spec to use query parameters instead of request body

Browse Source
This commit is contained in:
advplyr 2024-06-13 17:13:55 -05:00
parent baf5f7fbc3
commit d6438590d7
2 changed files with 128 additions and 163 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
docs/controllers/LibraryController.yaml
View File

@ -322,30 +322,48 @@ paths:
description: Get series in a library. Filtering and sorting can be applied. description: Get series in a library. Filtering and sorting can be applied.
tags: tags:
- Libraries - Libraries
requestBody: parameters:
required: false - in: query
description: The filters to apply to the requested library series. name: limit
content: description: The number of series to return. If 0, all series are returned.
application/json: example: 10
schema: schema:
type: object type: integer
properties: default: 0
limit: - in: query
$ref: '../schemas.yaml#/components/schemas/limit' name: page
page: description: The page number (zero indexed) to return. If no limit is specified, then page will have no effect.
$ref: '../schemas.yaml#/components/schemas/page' example: 0
sort: schema:
description: The field to sort by from the request. type: integer
type: string default: 0
enum: ['name', 'numBooks', 'totalDuration', 'addedAt', 'lastBookAdded', 'lastBookUpdated'] - in: query
example: 'numBooks' name: sort
default: 'name' description: The field to sort by from the request.
desc: example: 'numBooks'
$ref: '../schemas.yaml#/components/schemas/sortDesc' schema:
filter: type: string
$ref: '#/components/schemas/libraryFilter' enum: ['name', 'numBooks', 'totalDuration', 'addedAt', 'lastBookAdded', 'lastBookUpdated']
include: default: 'name'
$ref: '#/components/schemas/libraryInclude' - in: query
name: desc
description: Return items in reversed order if true.
example: true
schema:
type: boolean
default: false
- in: query
name: filter
description: The filter for the library.
example: 'media.metadata.title'
schema:
type: string
- in: query
name: include
description: The fields to include in the response. The only current option is `rssfeed`.
example: 'rssfeed'
schema:
type: string
responses: responses:
'200': '200':
description: getLibrarySeries OK description: getLibrarySeries OK

225
docs/openapi.json
View File

@ -47,9 +47,7 @@
"operationId": "getAuthorById", "operationId": "getAuthorById",
"summary": "Get an author by ID", "summary": "Get an author by ID",
"description": "Get an author by ID. The author's books and series can be included in the response.", "description": "Get an author by ID. The author's books and series can be included in the response.",
"tags": [ "tags": ["Authors"],
"Authors"
],
"requestBody": { "requestBody": {
"required": false, "required": false,
"description": "The author object to create.", "description": "The author object to create.",
@ -88,9 +86,7 @@
"operationId": "updateAuthorById", "operationId": "updateAuthorById",
"summary": "Update an author by ID", "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.", "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": [ "tags": ["Authors"],
"Authors"
],
"requestBody": { "requestBody": {
"description": "The author object to update.", "description": "The author object to update.",
"content": { "content": {
@ -144,9 +140,7 @@
"operationId": "deleteAuthorById", "operationId": "deleteAuthorById",
"summary": "Delete an author by ID", "summary": "Delete an author by ID",
"description": "Delete an author by ID. This will remove the author from all books.", "description": "Delete an author by ID. This will remove the author from all books.",
"tags": [ "tags": ["Authors"],
"Authors"
],
"responses": { "responses": {
"200": { "200": {
"description": "deleteAuthorById OK", "description": "deleteAuthorById OK",
@ -181,9 +175,7 @@
"operationId": "getAuthorImageById", "operationId": "getAuthorImageById",
"summary": "Get an author image by author ID", "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.", "description": "Get an author image by author ID. The image will be returned in the requested format and size.",
"tags": [ "tags": ["Authors"],
"Authors"
],
"requestBody": { "requestBody": {
"required": false, "required": false,
"description": "The author image to get.", "description": "The author image to get.",
@ -241,9 +233,7 @@
"operationId": "addAuthorImageById", "operationId": "addAuthorImageById",
"summary": "Add an author image to the server", "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.", "description": "Add an author image to the server. The image will be downloaded from the provided URL and stored on the server.",
"tags": [ "tags": ["Authors"],
"Authors"
],
"requestBody": { "requestBody": {
"required": true, "required": true,
"description": "The author image to add by URL.", "description": "The author image to add by URL.",
@ -276,9 +266,7 @@
"operationId": "updateAuthorImageById", "operationId": "updateAuthorImageById",
"summary": "Update an author image by author ID", "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.", "description": "Update an author image by author ID. The image will be resized if the width, height, or format is provided.",
"tags": [ "tags": ["Authors"],
"Authors"
],
"requestBody": { "requestBody": {
"description": "The author image to update.", "description": "The author image to update.",
"content": { "content": {
@ -323,9 +311,7 @@
"operationId": "deleteAuthorImageById", "operationId": "deleteAuthorImageById",
"summary": "Delete an author image by author ID", "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.", "description": "Delete an author image by author ID. This will remove the image from the server and the database.",
"tags": [ "tags": ["Authors"],
"Authors"
],
"responses": { "responses": {
"200": { "200": {
"description": "deleteAuthorImageById OK" "description": "deleteAuthorImageById OK"
@ -352,9 +338,7 @@
"operationId": "matchAuthorById", "operationId": "matchAuthorById",
"summary": "Match the author against Audible using quick match", "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.", "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": [ "tags": ["Authors"],
"Authors"
],
"requestBody": { "requestBody": {
"required": true, "required": true,
"description": "The author object to match against an online provider.", "description": "The author object to match against an online provider.",
@ -406,9 +390,7 @@
"operationId": "getLibraries", "operationId": "getLibraries",
"summary": "Get all libraries on server", "summary": "Get all libraries on server",
"description": "Get all libraries on server.", "description": "Get all libraries on server.",
"tags": [ "tags": ["Libraries"],
"Libraries"
],
"responses": { "responses": {
"200": { "200": {
"description": "getLibraries OK", "description": "getLibraries OK",
@ -429,19 +411,14 @@
"operationId": "createLibrary", "operationId": "createLibrary",
"summary": "Create a new library on server", "summary": "Create a new library on server",
"description": "Create a new library on server.", "description": "Create a new library on server.",
"tags": [ "tags": ["Libraries"],
"Libraries"
],
"requestBody": { "requestBody": {
"description": "The library object to create.", "description": "The library object to create.",
"content": { "content": {
"application/json": { "application/json": {
"schema": { "schema": {
"type": "object", "type": "object",
"required": [ "required": ["name", "folders"],
"name",
"folders"
],
"properties": { "properties": {
"name": { "name": {
"$ref": "#/components/schemas/libraryName" "$ref": "#/components/schemas/libraryName"
@ -495,9 +472,7 @@
"operationId": "getLibraryById", "operationId": "getLibraryById",
"summary": "Get a single library by ID on server", "summary": "Get a single library by ID on server",
"description": "Get a single library by ID on server.", "description": "Get a single library by ID on server.",
"tags": [ "tags": ["Libraries"],
"Libraries"
],
"responses": { "responses": {
"200": { "200": {
"$ref": "#/components/responses/library200" "$ref": "#/components/responses/library200"
@ -511,9 +486,7 @@
"operationId": "updateLibraryById", "operationId": "updateLibraryById",
"summary": "Update a single library by ID on server", "summary": "Update a single library by ID on server",
"description": "Update a single library by ID on server.", "description": "Update a single library by ID on server.",
"tags": [ "tags": ["Libraries"],
"Libraries"
],
"requestBody": { "requestBody": {
"required": true, "required": true,
"description": "The library object to update.", "description": "The library object to update.",
@ -561,9 +534,7 @@
"operationId": "deleteLibraryById", "operationId": "deleteLibraryById",
"summary": "Delete a single library by ID on server", "summary": "Delete a single library by ID on server",
"description": "Delete a single library by ID on server and return the deleted object.", "description": "Delete a single library by ID on server and return the deleted object.",
"tags": [ "tags": ["Libraries"],
"Libraries"
],
"responses": { "responses": {
"200": { "200": {
"$ref": "#/components/responses/library200" "$ref": "#/components/responses/library200"
@ -590,9 +561,7 @@
"operationId": "getLibraryAuthors", "operationId": "getLibraryAuthors",
"summary": "Get all authors in a library", "summary": "Get all authors in a library",
"description": "Get all authors in a library by ID on server.", "description": "Get all authors in a library by ID on server.",
"tags": [ "tags": ["Libraries"],
"Libraries"
],
"responses": { "responses": {
"200": { "200": {
"description": "getLibraryAuthors OK", "description": "getLibraryAuthors OK",
@ -634,9 +603,7 @@
"operationId": "getLibraryItems", "operationId": "getLibraryItems",
"summary": "Get items in a library", "summary": "Get items in a library",
"description": "Get items in a library by ID on server.", "description": "Get items in a library by ID on server.",
"tags": [ "tags": ["Libraries"],
"Libraries"
],
"requestBody": { "requestBody": {
"required": false, "required": false,
"description": "The filters to apply to the requested library items.", "description": "The filters to apply to the requested library items.",
@ -745,9 +712,7 @@
"operationId": "deleteLibraryIssues", "operationId": "deleteLibraryIssues",
"summary": "Delete items with issues in a library.", "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.", "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": [ "tags": ["Libraries"],
"Libraries"
],
"responses": { "responses": {
"200": { "200": {
"description": "deleteLibraryIssues OK", "description": "deleteLibraryIssues OK",
@ -782,51 +747,68 @@
"operationId": "getLibrarySeries", "operationId": "getLibrarySeries",
"summary": "Get library series", "summary": "Get library series",
"description": "Get series in a library. Filtering and sorting can be applied.", "description": "Get series in a library. Filtering and sorting can be applied.",
"tags": [ "tags": ["Libraries"],
"Libraries" "parameters": [
], {
"requestBody": { "in": "query",
"required": false, "name": "limit",
"description": "The filters to apply to the requested library series.", "description": "The number of series to return. If 0, all series are returned.",
"content": { "example": 10,
"application/json": { "schema": {
"schema": { "type": "integer",
"type": "object", "default": 0
"properties": { }
"limit": { },
"$ref": "#/components/schemas/limit" {
}, "in": "query",
"page": { "name": "page",
"$ref": "#/components/schemas/page" "description": "The page number (zero indexed) to return. If no limit is specified, then page will have no effect.",
}, "example": 0,
"sort": { "schema": {
"description": "The field to sort by from the request.", "type": "integer",
"type": "string", "default": 0
"enum": [ }
"name", },
"numBooks", {
"totalDuration", "in": "query",
"addedAt", "name": "sort",
"lastBookAdded", "description": "The field to sort by from the request.",
"lastBookUpdated" "example": "numBooks",
], "schema": {
"example": "numBooks", "type": "string",
"default": "name" "enum": ["name", "numBooks", "totalDuration", "addedAt", "lastBookAdded", "lastBookUpdated"],
}, "default": "name"
"desc": { }
"$ref": "#/components/schemas/sortDesc" },
}, {
"filter": { "in": "query",
"$ref": "#/components/schemas/libraryFilter" "name": "desc",
}, "description": "Return items in reversed order if true.",
"include": { "example": true,
"$ref": "#/components/schemas/libraryInclude" "schema": {
} "type": "boolean",
} "default": false
} }
},
{
"in": "query",
"name": "filter",
"description": "The filter for the library.",
"example": "media.metadata.title",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "include",
"description": "The fields to include in the response. The only current option is `rssfeed`.",
"example": "rssfeed",
"schema": {
"type": "string"
} }
} }
}, ],
"responses": { "responses": {
"200": { "200": {
"description": "getLibrarySeries OK", "description": "getLibrarySeries OK",
@ -902,9 +884,7 @@
"summary": "Get single series in library", "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.", "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, "deprecated": true,
"tags": [ "tags": ["Libraries"],
"Libraries"
],
"requestBody": { "requestBody": {
"required": false, "required": false,
"description": "The filters to apply to the requested library series.", "description": "The filters to apply to the requested library series.",
@ -922,14 +902,7 @@
"sort": { "sort": {
"description": "The field to sort by from the request.", "description": "The field to sort by from the request.",
"type": "string", "type": "string",
"enum": [ "enum": ["name", "numBooks", "totalDuration", "addedAt", "lastBookAdded", "lastBookUpdated"],
"name",
"numBooks",
"totalDuration",
"addedAt",
"lastBookAdded",
"lastBookUpdated"
],
"example": "numBooks", "example": "numBooks",
"default": "name" "default": "name"
}, },
@ -981,9 +954,7 @@
], ],
"get": { "get": {
"operationId": "getSeries", "operationId": "getSeries",
"tags": [ "tags": ["Series"],
"Series"
],
"summary": "Get series", "summary": "Get series",
"description": "Get a series by ID.", "description": "Get a series by ID.",
"requestBody": { "requestBody": {
@ -998,12 +969,7 @@
"type": "string", "type": "string",
"description": "A comma separated list of what to include with the series.", "description": "A comma separated list of what to include with the series.",
"example": "progress,rssfeed", "example": "progress,rssfeed",
"enum": [ "enum": ["progress", "rssfeed", "progress,rssfeed", "rssfeed,progress"]
"progress",
"rssfeed",
"progress,rssfeed",
"rssfeed,progress"
]
} }
} }
} }
@ -1028,9 +994,7 @@
}, },
"patch": { "patch": {
"operationId": "updateSeries", "operationId": "updateSeries",
"tags": [ "tags": ["Series"],
"Series"
],
"summary": "Update series", "summary": "Update series",
"description": "Update a series by ID.", "description": "Update a series by ID.",
"requestBody": { "requestBody": {
@ -1156,10 +1120,7 @@
"mediaType": { "mediaType": {
"type": "string", "type": "string",
"description": "The type of media, will be book or podcast.", "description": "The type of media, will be book or podcast.",
"enum": [ "enum": ["book", "podcast"]
"book",
"podcast"
]
}, },
"libraryItemBase": { "libraryItemBase": {
"type": "object", "type": "object",
@ -1244,11 +1205,7 @@
"items": { "items": {
"type": "string" "type": "string"
}, },
"example": [ "example": ["Fantasy", "Sci-Fi", "Nonfiction: History"]
"Fantasy",
"Sci-Fi",
"Nonfiction: History"
]
}, },
"publishedYear": { "publishedYear": {
"description": "The year the book was published. Will be null if unknown.", "description": "The year the book was published. Will be null if unknown.",
@ -1346,10 +1303,7 @@
"items": { "items": {
"type": "string" "type": "string"
}, },
"example": [ "example": ["To Be Read", "Genre: Nonfiction"]
"To Be Read",
"Genre: Nonfiction"
]
}, },
"durationSec": { "durationSec": {
"description": "The total length (in seconds) of the item or file.", "description": "The total length (in seconds) of the item or file.",
@ -1635,14 +1589,7 @@
"items": { "items": {
"type": "string" "type": "string"
}, },
"example": [ "example": ["folderStructure", "audioMetatags", "nfoFile", "txtFiles", "opfFile", "absMetadata"]
"folderStructure",
"audioMetatags",
"nfoFile",
"txtFiles",
"opfFile",
"absMetadata"
]
}, },
"podcastSearchRegion": { "podcastSearchRegion": {
"description": "The region to use when searching for podcasts.", "description": "The region to use when searching for podcasts.",