mirror of
https://github.com/advplyr/audiobookshelf.git
synced 2025-05-24 01:13:00 -04:00
baf5f7fbc3
* 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
436 lines
15 KiB
YAML
436 lines
15 KiB
YAML
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'
|