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

Merge pull request #3095 from nichwall/parameter_changes

Browse Source 
Change: `requestBody` to `parameter`, allow commas in queries
This commit is contained in:
advplyr 2024-06-23 07:41:21 -05:00 committed by GitHub
commit 09bcc1191f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 429 additions and 263 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
docs/controllers/AuthorController.yaml
View File

@ -74,17 +74,14 @@ paths:
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'
parameters:
- in: query
name: include
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.
allowReserved: true
schema:
type: string
example: 'items,series'
responses:
'200':
description: getAuthorById OK
@ -150,10 +147,21 @@ paths:
required: true
schema:
$ref: '../objects/entities/Author.yaml#/components/schemas/authorId'
- name: token
in: query
description: API token
schema:
type: string
- name: ts
in: query
description: Updated at value
schema:
type: integer
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.
security: [] # No security for getting author image
tags:
- Authors
requestBody:

165
docs/controllers/LibraryController.yaml
View File

@ -57,6 +57,32 @@ components:
description: The fields to include in the response. The only current option is `rssfeed`.
type: string
example: 'rssfeed'
parameters:
limit:
in: query
name: limit
description: The number of items to return. This the size of a single page for the optional `page` query.
example: 10
schema:
type: integer
default: 0
page:
in: query
name: page
description: The page number (zero indexed) to return. If no limit is specified, then page will have no effect.
example: 0
schema:
type: integer
default: 0
desc:
in: query
name: desc
description: Return items in reversed order if true.
example: 0
schema:
type: integer
default: 0
responses:
library200:
description: Library found.
@ -135,6 +161,12 @@ paths:
description: Get a single library by ID on server.
tags:
- Libraries
parameters:
- in: query
name: include
schema:
type: string
- $ref: '../schemas.yaml#/components/parameters/minified'
responses:
'200':
$ref: '#/components/responses/library200'
@ -222,30 +254,37 @@ paths:
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'
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page'
- in: query
name: sort
description: The field to sort by from the request.
example: 'numBooks'
schema:
type: string
default: 'name'
- $ref: '#/components/parameters/desc'
- 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`.
allowReserved: true
example: 'rssfeed'
schema:
type: string
- $ref: '../schemas.yaml#/components/parameters/minified'
- in: query
name: collapseSeries
description: Whether to collapse series into a single cover
schema:
type: integer
default: 0
responses:
'200':
description: getLibraryItems OK
@ -323,20 +362,8 @@ paths:
tags:
- Libraries
parameters:
- in: query
name: limit
description: The number of series to return. If 0, all series are returned.
example: 10
schema:
type: integer
default: 0
- in: query
name: page
description: The page number (zero indexed) to return. If no limit is specified, then page will have no effect.
example: 0
schema:
type: integer
default: 0
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page'
- in: query
name: sort
description: The field to sort by from the request.
@ -345,13 +372,7 @@ paths:
type: string
enum: ['name', 'numBooks', 'totalDuration', 'addedAt', 'lastBookAdded', 'lastBookUpdated']
default: 'name'
- in: query
name: desc
description: Return items in reversed order if true.
example: true
schema:
type: boolean
default: false
- $ref: '#/components/parameters/desc'
- in: query
name: filter
description: The filter for the library.
@ -361,9 +382,11 @@ paths:
- in: query
name: include
description: The fields to include in the response. The only current option is `rssfeed`.
allowReserved: true
example: 'rssfeed'
schema:
type: string
- $ref: '../schemas.yaml#/components/parameters/minified'
responses:
'200':
description: getLibrarySeries OK
@ -416,32 +439,32 @@ paths:
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'
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page'
- in: query
name: sort
description: The field to sort by from the request.
example: 'numBooks'
schema:
type: string
enum: ['name', 'numBooks', 'totalDuration', 'addedAt', 'lastBookAdded', 'lastBookUpdated']
default: 'name'
- $ref: '#/components/parameters/desc'
- in: query
name: filter
description: The filter for the library.
example: 'media.metadata.title'
schema:
type: string
- $ref: '../schemas.yaml#/components/parameters/minified'
- in: query
name: include
description: The fields to include in the response. The only current option is `rssfeed`.
allowReserved: true
example: 'rssfeed'
schema:
type: string
responses:
'200':
description: getLibrarySeriesById OK

488
docs/openapi.json
View File

@ -47,25 +47,21 @@
"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/libraryId"
}
}
}
}
"tags": [
"Authors"
],
"parameters": [
{
"in": "query",
"name": "include",
"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.",
"allowReserved": true,
"schema": {
"type": "string"
},
"example": "items,series"
}
},
],
"responses": {
"200": {
"description": "getAuthorById OK",
@ -86,7 +82,9 @@
"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"],
"tags": [
"Authors"
],
"requestBody": {
"description": "The author object to update.",
"content": {
@ -140,7 +138,9 @@
"operationId": "deleteAuthorById",
"summary": "Delete an author by ID",
"description": "Delete an author by ID. This will remove the author from all books.",
"tags": ["Authors"],
"tags": [
"Authors"
],
"responses": {
"200": {
"description": "deleteAuthorById OK",
@ -169,13 +169,32 @@
"schema": {
"$ref": "#/components/schemas/authorId"
}
},
{
"name": "token",
"in": "query",
"description": "API token",
"schema": {
"type": "string"
}
},
{
"name": "ts",
"in": "query",
"description": "Updated at value",
"schema": {
"type": "integer"
}
}
],
"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"],
"security": [],
"tags": [
"Authors"
],
"requestBody": {
"required": false,
"description": "The author image to get.",
@ -233,7 +252,9 @@
"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"],
"tags": [
"Authors"
],
"requestBody": {
"required": true,
"description": "The author image to add by URL.",
@ -266,7 +287,9 @@
"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"],
"tags": [
"Authors"
],
"requestBody": {
"description": "The author image to update.",
"content": {
@ -311,7 +334,9 @@
"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"],
"tags": [
"Authors"
],
"responses": {
"200": {
"description": "deleteAuthorImageById OK"
@ -338,7 +363,9 @@
"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"],
"tags": [
"Authors"
],
"requestBody": {
"required": true,
"description": "The author object to match against an online provider.",
@ -390,7 +417,9 @@
"operationId": "getLibraries",
"summary": "Get all libraries on server",
"description": "Get all libraries on server.",
"tags": ["Libraries"],
"tags": [
"Libraries"
],
"responses": {
"200": {
"description": "getLibraries OK",
@ -411,14 +440,19 @@
"operationId": "createLibrary",
"summary": "Create a new library on server",
"description": "Create a new library on server.",
"tags": ["Libraries"],
"tags": [
"Libraries"
],
"requestBody": {
"description": "The library object to create.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["name", "folders"],
"required": [
"name",
"folders"
],
"properties": {
"name": {
"$ref": "#/components/schemas/libraryName"
@ -472,7 +506,21 @@
"operationId": "getLibraryById",
"summary": "Get a single library by ID on server",
"description": "Get a single library by ID on server.",
"tags": ["Libraries"],
"tags": [
"Libraries"
],
"parameters": [
{
"in": "query",
"name": "include",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/minified"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/library200"
@ -486,7 +534,9 @@
"operationId": "updateLibraryById",
"summary": "Update a single library by ID on server",
"description": "Update a single library by ID on server.",
"tags": ["Libraries"],
"tags": [
"Libraries"
],
"requestBody": {
"required": true,
"description": "The library object to update.",
@ -534,7 +584,9 @@
"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"],
"tags": [
"Libraries"
],
"responses": {
"200": {
"$ref": "#/components/responses/library200"
@ -561,7 +613,9 @@
"operationId": "getLibraryAuthors",
"summary": "Get all authors in a library",
"description": "Get all authors in a library by ID on server.",
"tags": ["Libraries"],
"tags": [
"Libraries"
],
"responses": {
"200": {
"description": "getLibraryAuthors OK",
@ -603,44 +657,61 @@
"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": "#/components/schemas/limit"
},
"page": {
"$ref": "#/components/schemas/page"
},
"sort": {
"$ref": "#/components/schemas/librarySort"
},
"desc": {
"$ref": "#/components/schemas/sortDesc"
},
"filter": {
"$ref": "#/components/schemas/libraryFilter"
},
"minified": {
"$ref": "#/components/schemas/minified"
},
"collapseSeries": {
"$ref": "#/components/schemas/libraryCollapseSeries"
},
"include": {
"$ref": "#/components/schemas/libraryInclude"
}
}
}
"tags": [
"Libraries"
],
"parameters": [
{
"$ref": "#/components/parameters/limit"
},
{
"$ref": "#/components/parameters/page"
},
{
"in": "query",
"name": "sort",
"description": "The field to sort by from the request.",
"example": "numBooks",
"schema": {
"type": "string",
"default": "name"
}
},
{
"$ref": "#/components/parameters/desc"
},
{
"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`.",
"allowReserved": true,
"example": "rssfeed",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/minified"
},
{
"in": "query",
"name": "collapseSeries",
"description": "Whether to collapse series into a single cover",
"schema": {
"type": "integer",
"default": 0
}
}
},
],
"responses": {
"200": {
"description": "getLibraryItems OK",
@ -712,7 +783,9 @@
"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"],
"tags": [
"Libraries"
],
"responses": {
"200": {
"description": "deleteLibraryIssues OK",
@ -747,27 +820,15 @@
"operationId": "getLibrarySeries",
"summary": "Get library series",
"description": "Get series in a library. Filtering and sorting can be applied.",
"tags": ["Libraries"],
"tags": [
"Libraries"
],
"parameters": [
{
"in": "query",
"name": "limit",
"description": "The number of series to return. If 0, all series are returned.",
"example": 10,
"schema": {
"type": "integer",
"default": 0
}
"$ref": "#/components/parameters/limit"
},
{
"in": "query",
"name": "page",
"description": "The page number (zero indexed) to return. If no limit is specified, then page will have no effect.",
"example": 0,
"schema": {
"type": "integer",
"default": 0
}
"$ref": "#/components/parameters/page"
},
{
"in": "query",
@ -776,19 +837,19 @@
"example": "numBooks",
"schema": {
"type": "string",
"enum": ["name", "numBooks", "totalDuration", "addedAt", "lastBookAdded", "lastBookUpdated"],
"enum": [
"name",
"numBooks",
"totalDuration",
"addedAt",
"lastBookAdded",
"lastBookUpdated"
],
"default": "name"
}
},
{
"in": "query",
"name": "desc",
"description": "Return items in reversed order if true.",
"example": true,
"schema": {
"type": "boolean",
"default": false
}
"$ref": "#/components/parameters/desc"
},
{
"in": "query",
@ -803,10 +864,14 @@
"in": "query",
"name": "include",
"description": "The fields to include in the response. The only current option is `rssfeed`.",
"allowReserved": true,
"example": "rssfeed",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/minified"
}
],
"responses": {
@ -884,45 +949,60 @@
"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": "#/components/schemas/limit"
},
"page": {
"$ref": "#/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": "#/components/schemas/sortDesc"
},
"filter": {
"$ref": "#/components/schemas/libraryFilter"
},
"minified": {
"$ref": "#/components/schemas/minified"
},
"include": {
"$ref": "#/components/schemas/libraryInclude"
}
}
}
"tags": [
"Libraries"
],
"parameters": [
{
"$ref": "#/components/parameters/limit"
},
{
"$ref": "#/components/parameters/page"
},
{
"in": "query",
"name": "sort",
"description": "The field to sort by from the request.",
"example": "numBooks",
"schema": {
"type": "string",
"enum": [
"name",
"numBooks",
"totalDuration",
"addedAt",
"lastBookAdded",
"lastBookUpdated"
],
"default": "name"
}
},
{
"$ref": "#/components/parameters/desc"
},
{
"in": "query",
"name": "filter",
"description": "The filter for the library.",
"example": "media.metadata.title",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/minified"
},
{
"in": "query",
"name": "include",
"description": "The fields to include in the response. The only current option is `rssfeed`.",
"allowReserved": true,
"example": "rssfeed",
"schema": {
"type": "string"
}
}
},
],
"responses": {
"200": {
"description": "getLibrarySeriesById OK",
@ -954,7 +1034,9 @@
],
"get": {
"operationId": "getSeries",
"tags": ["Series"],
"tags": [
"Series"
],
"summary": "Get series",
"description": "Get a series by ID.",
"requestBody": {
@ -969,7 +1051,12 @@
"type": "string",
"description": "A comma separated list of what to include with the series.",
"example": "progress,rssfeed",
"enum": ["progress", "rssfeed", "progress,rssfeed", "rssfeed,progress"]
"enum": [
"progress",
"rssfeed",
"progress,rssfeed",
"rssfeed,progress"
]
}
}
}
@ -994,7 +1081,9 @@
},
"patch": {
"operationId": "updateSeries",
"tags": ["Series"],
"tags": [
"Series"
],
"summary": "Update series",
"description": "Update a series by ID.",
"requestBody": {
@ -1048,17 +1137,6 @@
"format": "uuid",
"example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b"
},
"authorInclude": {
"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"
},
"libraryId": {
"type": "string",
"description": "The ID of the library.",
"format": "uuid",
"example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b"
},
"authorAsin": {
"description": "The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.",
"type": "string",
@ -1111,6 +1189,12 @@
"format": "[0-9]*",
"example": "649644248522215260"
},
"libraryId": {
"type": "string",
"description": "The ID of the library.",
"format": "uuid",
"example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b"
},
"folderId": {
"type": "string",
"description": "The ID of the folder.",
@ -1120,7 +1204,10 @@
"mediaType": {
"type": "string",
"description": "The type of media, will be book or podcast.",
"enum": ["book", "podcast"]
"enum": [
"book",
"podcast"
]
},
"libraryItemBase": {
"type": "object",
@ -1205,7 +1292,11 @@
"items": {
"type": "string"
},
"example": ["Fantasy", "Sci-Fi", "Nonfiction: History"]
"example": [
"Fantasy",
"Sci-Fi",
"Nonfiction: History"
]
},
"publishedYear": {
"description": "The year the book was published. Will be null if unknown.",
@ -1303,7 +1394,10 @@
"items": {
"type": "string"
},
"example": ["To Be Read", "Genre: Nonfiction"]
"example": [
"To Be Read",
"Genre: Nonfiction"
]
},
"durationSec": {
"description": "The total length (in seconds) of the item or file.",
@ -1589,7 +1683,14 @@
"items": {
"type": "string"
},
"example": ["folderStructure", "audioMetatags", "nfoFile", "txtFiles", "opfFile", "absMetadata"]
"example": [
"folderStructure",
"audioMetatags",
"nfoFile",
"txtFiles",
"opfFile",
"absMetadata"
]
},
"podcastSearchRegion": {
"description": "The region to use when searching for podcasts.",
@ -1698,6 +1799,11 @@
}
]
},
"total": {
"description": "The total number of items in the response.",
"type": "integer",
"example": 100
},
"limit": {
"description": "The number of items to return. If 0, no items are returned.",
"type": "integer",
@ -1710,20 +1816,19 @@
"example": 1,
"default": 0
},
"librarySort": {
"description": "The sort order of the library. For example, to sort by title use 'sort=media.metadata.title'.",
"sortBy": {
"type": "string",
"description": "The field to sort by from the request.",
"example": "media.metadata.title"
},
"sortDesc": {
"description": "Return items in reversed order if true.",
"description": "Whether to sort in descending order.",
"type": "boolean",
"example": true,
"default": false
"example": true
},
"libraryFilter": {
"description": "The filter for the library.",
"filterBy": {
"type": "string",
"description": "The field to filter by from the request. TODO",
"example": "media.metadata.title"
},
"minified": {
@ -1732,37 +1837,16 @@
"example": true,
"default": false
},
"libraryCollapseSeries": {
"description": "Whether to collapse series.",
"collapseSeries": {
"type": "boolean",
"example": true,
"default": false
"description": "Whether collapse series was set in the request.",
"example": true
},
"libraryInclude": {
"description": "The fields to include in the response. The only current option is `rssfeed`.",
"type": "string",
"example": "rssfeed"
},
"total": {
"description": "The total number of items in the response.",
"type": "integer",
"example": 100
},
"sortBy": {
"type": "string",
"description": "The field to sort by from the request.",
"example": "media.metadata.title"
},
"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
},
"sequence": {
"description": "The position in the series the book is.",
"type": "string",
@ -1936,6 +2020,48 @@
}
}
}
},
"parameters": {
"minified": {
"in": "query",
"name": "minified",
"description": "Return minified items if true",
"schema": {
"type": "integer",
"minimum": 0,
"example": 1
}
},
"limit": {
"in": "query",
"name": "limit",
"description": "The number of items to return. This the size of a single page for the optional `page` query.",
"example": 10,
"schema": {
"type": "integer",
"default": 0
}
},
"page": {
"in": "query",
"name": "page",
"description": "The page number (zero indexed) to return. If no limit is specified, then page will have no effect.",
"example": 0,
"schema": {
"type": "integer",
"default": 0
}
},
"desc": {
"in": "query",
"name": "desc",
"description": "Return items in reversed order if true.",
"example": 0,
"schema": {
"type": "integer",
"default": 0
}
}
}
}
}

9
docs/schemas.yaml
View File

@ -60,3 +60,12 @@ components:
type: string
example: 'us'
default: 'us'
parameters:
minified:
in: query
name: minified
description: Return minified items if true
schema:
type: integer
minimum: 0
example: 1