From afe40be957eda7d7679f69e78ff0c16f162d2af9 Mon Sep 17 00:00:00 2001 From: Nicholas Wallace Date: Sat, 30 Mar 2024 23:47:13 +0000 Subject: [PATCH 01/39] Initial large file --- docs/spec.yaml | 972 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 972 insertions(+) create mode 100644 docs/spec.yaml diff --git a/docs/spec.yaml b/docs/spec.yaml new file mode 100644 index 00000000..dfe95b69 --- /dev/null +++ b/docs/spec.yaml @@ -0,0 +1,972 @@ +openapi: 3.0.0 +info: + title: Audiobookshelf API + version: 0.1.0 + description: Audiobookshelf API with autogenerated OpenAPI doc + +servers: + - url: http://localhost:3000 + description: Development server + +components: + schemas: + mediaType: + type: string + description: The type of media, will be book or podcast. + enum: [book, podcast] + mediaMinified: + description: The minified media of the library item. + oneOf: + - $ref: '#/components/schemas/bookMinified' + bookCoverPath: + description: The absolute path on the server of the cover file. Will be null if there is no cover. + type: string + nullable: true + example: /audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg + bookBase: + type: object + description: Base book schema + properties: + libraryItemId: + $ref: '#/components/schemas/libraryItemId' + coverPath: + $ref: '#/components/schemas/bookCoverPath' + tags: + $ref: '#/components/schemas/tags' + audioFiles: + type: array + items: + $ref: '#/components/schemas/audioFile' + chapters: + type: array + items: + $ref: '#/components/schemas/bookChapter' + missingParts: + description: Any parts missing from the book by track index. + type: array + items: + type: integer + ebookFile: + $ref: '#/components/schemas/ebookFile' + bookMinified: + type: object + description: Minified book schema. Does not depend on `bookBase` because there's pretty much no overlap. + properties: + metadata: + $ref: '#/components/schemas/bookMetadataMinified' + coverPath: + $ref: '#/components/schemas/bookCoverPath' + tags: + $ref: '#/components/schemas/tags' + numTracks: + description: The number of tracks the book's audio files have. + type: integer + example: 1 + numAudioFiles: + description: The number of audio files the book has. + type: integer + example: 1 + numChapters: + description: The number of chapters the book has. + type: integer + example: 1 + numMissingParts: + description: The total number of missing parts the book has. + type: integer + example: 0 + numInvalidAudioFiles: + description: The number of invalid audio files the book has. + type: integer + example: 0 + duration: + $ref: '#/components/schemas/durationSec' + size: + $ref: '#/components/schemas/size' + ebookFormat: + description: The format of ebook of the book. Will be null if the book is an audiobook. + type: string + nullable: true + narrators: + description: The narrators of the audiobook. + type: array + items: + type: string + example: Sam Tsoutsouvas + bookMetadataBase: + type: object + description: The base book metadata object for minified, normal, and extended schemas to inherit from. + properties: + title: + description: The title of the book. Will be null if unknown. + type: string + nullable: true + example: Wizards First Rule + subtitle: + description: The subtitle of the book. Will be null if there is no subtitle. + type: string + nullable: true + genres: + description: The genres of the book. + type: array + items: + type: string + example: ["Fantasy", "Sci-Fi", "Nonfiction: History"] + publishedYear: + description: The year the book was published. Will be null if unknown. + type: string + nullable: true + example: '2008' + publishedDate: + description: The date the book was published. Will be null if unknown. + type: string + nullable: true + publisher: + description: The publisher of the book. Will be null if unknown. + type: string + nullable: true + example: Brilliance Audio + description: + description: A description for the book. Will be null if empty. + type: string + nullable: true + example: >- + The masterpiece that started Terry Goodkind's New York Times bestselling + epic Sword of Truth In the aftermath of the brutal murder of his father, + a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest + sanctuary seeking help...and more. His world, his very beliefs, are + shattered when ancient debts come due with thundering violence. In a + dark age it takes courage to live, and more than mere courage to + challenge those who hold dominion, Richard and Kahlan must take up that + challenge or become the next victims. Beyond awaits a bewitching land + where even the best of their hearts could betray them. Yet, Richard + fears nothing so much as what secrets his sword might reveal about his + own soul. Falling in love would destroy them - for reasons Richard can't + imagine and Kahlan dare not say. In their darkest hour, hunted + relentlessly, tormented by treachery and loss, Kahlan calls upon Richard + to reach beyond his sword - to invoke within himself something more + noble. Neither knows that the rules of battle have just changed...or + that their time has run out. Wizard's First Rule is the beginning. One + book. One Rule. Witness the birth of a legend. + isbn: + description: The ISBN of the book. Will be null if unknown. + type: string + nullable: true + asin: + description: The ASIN of the book. Will be null if unknown. + type: string + nullable: true + example: B002V0QK4C + language: + description: The language of the book. Will be null if unknown. + type: string + nullable: true + explicit: + description: Whether the book has been marked as explicit. + type: boolean + example: false + bookMetadataMinified: + type: object + description: The minified metadata for a book in the database. + allOf: + - $ref : '#/components/schemas/bookMetadataBase' + - type: object + properties: + titleIgnorePrefix: + description: The title of the book with any prefix moved to the end. + type: string + authorName: + description: The name of the book's author(s). + type: string + example: Terry Goodkind + authorNameLF: + description: The name of the book's author(s) with last names first. + type: string + example: Goodkind, Terry + narratorName: + description: The name of the audiobook's narrator(s). + type: string + example: Sam Tsoutsouvas + seriesName: + description: The name of the book's series. + type: string + example: Sword of Truth + bookChapter: + type: object + description: A book chapter. Includes the title and timestamps. + properties: + id: + description: The ID of the book chapter. + type: integer + example: 0 + start: + description: When in the book (in seconds) the chapter starts. + type: integer + example: 0 + end: + description: When in the book (in seconds) the chapter ends. + type: number + example: 6004.6675 + title: + description: The title of the chapter. + type: string + example: Wizards First Rule 01 Chapter 1 + audioFile: + type: object + description: An audio file for a book. Includes audio metadata and track numbers. + properties: + index: + description: The index of the audio file. + type: integer + example: 1 + ino: + $ref: '#/components/schemas/inode' + metadata: + $ref: '#/components/schemas/fileMetadata' + addedAt: + $ref: '#/components/schemas/addedAt' + updatedAt: + $ref: '#/components/schemas/updatedAt' + trackNumFromMeta: + description: The track number of the audio file as pulled from the file's metadata. Will be null if unknown. + type: integer + nullable: true + example: 1 + discNumFromMeta: + description: The disc number of the audio file as pulled from the file's metadata. Will be null if unknown. + type: string + nullable: true + trackNumFromFilename: + description: The track number of the audio file as determined from the file's name. Will be null if unknown. + type: integer + nullable: true + example: 1 + discNumFromFilename: + description: The disc number of the audio file as determined from the file's name. Will be null if unknown. + type: string + nullable: true + manuallyVerified: + description: Whether the audio file has been manually verified by a user. + type: boolean + invalid: + description: Whether the audio file is missing from the server. + type: boolean + exclude: + description: Whether the audio file has been marked for exclusion. + type: boolean + error: + description: Any error with the audio file. Will be null if there is none. + type: string + nullable: true + format: + description: The format of the audio file. + type: string + example: MP2/3 (MPEG audio layer 2/3) + duration: + $ref: '#/components/schemas/durationSec' + bitRate: + description: The bit rate (in bit/s) of the audio file. + type: integer + example: 64000 + language: + description: The language of the audio file. + type: string + nullable: true + codec: + description: The codec of the audio file. + type: string + example: mp3 + timeBase: + description: The time base of the audio file. + type: string + example: 1/14112000 + channels: + description: The number of channels the audio file has. + type: integer + example: 2 + channelLayout: + description: The layout of the audio file's channels. + type: string + example: stereo + chapters: + description: If the audio file is part of an audiobook, the chapters the file contains. + type: array + items: + $ref: '#/components/schemas/bookChapter' + embeddedCoverArt: + description: The type of embedded cover art in the audio file. Will be null if none exists. + type: string + nullable: true + metaTags: + $ref: '#/components/schemas/audioMetaTags' + mimeType: + description: The MIME type of the audio file. + type: string + example: audio/mpeg + ebookFile: + type: object + description: An ebook file for a library item. + nullable: true + properties: + ino: + $ref: '#/components/schemas/inode' + metadata: + $ref: '#/components/schemas/fileMetadata' + ebookFormat: + description: The ebook format of the ebook file. + type: string + example: epub + addedAt: + $ref: '#/components/schemas/addedAt' + updatedAt: + $ref: '#/components/schemas/updatedAt' + fileMetadata: + type: object + description: The metadata for a file, including the path, size, and unix timestamps of the file. + nullable: true + properties: + filename: + description: The filename of the file. + type: string + example: Wizards First Rule 01.mp3 + ext: + description: The file extension of the file. + type: string + example: .mp3 + path: + description: The absolute path on the server of the file. + type: string + example: >- + /audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry + Goodkind - SOT Bk01 - Wizards First Rule 01.mp3 + relPath: + description: The path of the file, relative to the book's or podcast's folder. + type: string + example: Wizards First Rule 01.mp3 + size: + $ref: '#/components/schemas/size' + mtimeMs: + description: The time (in ms since POSIX epoch) when the file was last modified on disk. + type: integer + example: 1632223180278 + ctimeMs: + description: The time (in ms since POSIX epoch) when the file status was changed on disk. + type: integer + example: 1645978261001 + birthtimeMs: + description: The time (in ms since POSIX epoch) when the file was created on disk. Will be 0 if unknown. + type: integer + example: 0 + audioMetaTags: + description: ID3 metadata tags pulled from the audio file on import. Only non-null tags will be returned in requests. + type: object + properties: + tagAlbum: + type: string + nullable: true + example: SOT Bk01 + tagArtist: + type: string + nullable: true + example: Terry Goodkind + tagGenre: + type: string + nullable: true + example: Audiobook Fantasy + tagTitle: + type: string + nullable: true + example: Wizards First Rule 01 + tagSeries: + type: string + nullable: true + tagSeriesPart: + type: string + nullable: true + tagTrack: + type: string + nullable: true + example: 01/20 + tagDisc: + type: string + nullable: true + tagSubtitle: + type: string + nullable: true + tagAlbumArtist: + type: string + nullable: true + example: Terry Goodkind + tagDate: + type: string + nullable: true + tagComposer: + type: string + nullable: true + example: Terry Goodkind + tagPublisher: + type: string + nullable: true + tagComment: + type: string + nullable: true + tagDescription: + type: string + nullable: true + tagEncoder: + type: string + nullable: true + tagEncodedBy: + type: string + nullable: true + tagIsbn: + type: string + nullable: true + tagLanguage: + type: string + nullable: true + tagASIN: + type: string + nullable: true + tagOverdriveMediaMarker: + type: string + nullable: true + tagOriginalYear: + type: string + nullable: true + tagReleaseCountry: + type: string + nullable: true + tagReleaseType: + type: string + nullable: true + tagReleaseStatus: + type: string + nullable: true + tagISRC: + type: string + nullable: true + tagMusicBrainzTrackId: + type: string + nullable: true + tagMusicBrainzAlbumId: + type: string + nullable: true + tagMusicBrainzAlbumArtistId: + type: string + nullable: true + tagMusicBrainzArtistId: + type: string + nullable: true + addedAt: + type: integer + description: The time (in ms since POSIX epoch) when added to the server. + example: 1633522963509 + createdAt: + type: integer + description: The time (in ms since POSIX epoch) when was created. + example: 1633522963509 + updatedAt: + type: integer + description: The time (in ms since POSIX epoch) when last updated. + example: 1633522963509 + size: + description: The total size (in bytes) of the item or file. + type: integer + example: 268824228 + durationSec: + description: The total length (in seconds) of the item or file. + type: number + example: 33854.905 + tags: + description: Tags applied to items. + type: array + items: + type: string + example: ["To Be Read", "Genre: Nonfiction"] + inode: + description: The inode of the item in the file system. + type: string + format: "[0-9]*" + example: '649644248522215260' + seriesId: + type: string + description: The ID of the series. + format: uuid + example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b + seriesName: + description: The name of the series. + type: string + example: Sword of Truth + folderId: + type: string + description: The ID of the folder. + format: uuid + example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b + folder: + type: object + description: Folder used in library + properties: + id: + $ref: '#/components/schemas/folderId' + fullPath: + description: The path on the server for the folder. (Read Only) + type: string + example: /podcasts + libraryId: + $ref: '#/components/schemas/libraryId' + addedAt: + $ref: '#/components/schemas/addedAt' + authorUpdated: + description: Whether the author was updated without errors. Will not exist if author was merged. + type: boolean + nullable: true + authorId: + type: string + description: The ID of the author. + format: uuid + example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b + authorASIN: + type: string + description: The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier. + nullable: true + example: B000APZOQA + authorName: + description: The name of the author. + type: string + example: Terry Goodkind + authorSeries: + type: object + description: Series and the included library items that an author has written. + properties: + id: + $ref: '#/components/schemas/seriesId' + name: + $ref: '#/components/schemas/seriesName' + items: + description: The items in the series. Each library item's media's metadata will have a `series` attribute, a `Series Sequence`, which is the matching series. + type: array + items: + $ref: '#/components/schemas/libraryItemMinified' + author: + description: An author object which includes a description and image path. + type: object + properties: + id: + $ref: '#/components/schemas/authorId' + asin: + $ref: '#/components/schemas/authorASIN' + name: + $ref: '#/components/schemas/authorName' + description: + description: A description of the author. Will be null if there is none. + type: string + nullable: true + example: | + Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork, + ‘The Sword of Truth’. He has written 30+ major, bestselling novels, has been published in more than 20 + languages world-wide, and has sold more than 26 Million books. ‘The Sword of Truth’ is a revered literary + tour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. Terry Goodkind's + brilliant books are character-driven stories, with a focus on the complexity of the human psyche. Goodkind + has an uncanny grasp for crafting compelling stories about people like you and me, trapped in terrifying + situations. + imagePath: + description: The absolute path for the author image located in the `metadata/` directory. Will be null if there is no image. + type: string + nullable: true + example: /metadata/authors/aut_bxxbyjiptmgb56yzoz.jpg + addedAt: + $ref: '#/components/schemas/addedAt' + updatedAt: + $ref: '#/components/schemas/updatedAt' + authorWithItems: + type: object + description: The author schema with an array of items they are associated with. + allOf: + - $ref: '#/components/schemas/author' + - type: object + properties: + libraryItems: + description: The items associated with the author + type: array + items: + $ref: '#/components/schemas/libraryItemMinified' + authorWithSeries: + type: object + description: The author schema with an array of items and series they are associated with. + allOf: + - $ref: '#/components/schemas/authorWithItems' + - type: object + properties: + series: + description: The series associated with the author + type: array + items: + $ref: '#/components/schemas/authorSeries' + authorMinified: + type: object + description: Minified author object which only contains the author name and ID. + properties: + id: + $ref: '#/components/schemas/authorId' + name: + $ref: '#/components/schemas/authorName' + authorExpanded: + type: object + description: The author schema with the total number of books in the library. + allOf: + - $ref: '#/components/schemas/author' + - type: object + properties: + numBooks: + description: The number of books associated with the author in the library. + type: integer + example: 1 + oldLibraryId: + type: string + description: The ID of the libraries created on server version 2.2.23 and before. + format: "lib_[a-z0-9]{18}" + example: lib_o78uaoeuh78h6aoeif + libraryId: + type: string + description: The ID of the library. + format: uuid + example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b + oldLibraryItemId: + description: The ID of library items on server version 2.2.23 and before. + type: string + nullable: true + format: "li_[a-z0-9]{18}" + example: li_o78uaoeuh78h6aoeif + libraryItemId: + type: string + description: The ID of library items after 2.3.0. + format: uuid + example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b + libraryItemBase: + type: object + description: Base library item schema + properties: + id: + $ref: '#/components/schemas/libraryItemId' + oldLibraryItemId: + $ref: '#/components/schemas/oldLibraryItemId' + ino: + $ref: '#/components/schemas/inode' + libraryId: + $ref: '#/components/schemas/libraryId' + folderId: + $ref: '#/components/schemas/folderId' + path: + description: The path of the library item on the server. + type: string + relPath: + description: The path, relative to the library folder, of the library item. + type: string + isFile: + description: Whether the library item is a single file in the root of the library folder. + type: boolean + mtimeMs: + description: The time (in ms since POSIX epoch) when the library item was last modified on disk. + type: integer + ctimeMs: + description: The time (in ms since POSIX epoch) when the library item status was changed on disk. + type: integer + birthtimeMs: + description: The time (in ms since POSIX epoch) when the library item was created on disk. Will be 0 if unknown. + type: integer + addedAt: + $ref: '#/components/schemas/addedAt' + updatedAt: + $ref: '#/components/schemas/updatedAt' + isMissing: + description: Whether the library item was scanned and no longer exists. + type: boolean + isInvalid: + description: Whether the library item was scanned and no longer has media files. + type: boolean + mediaType: + $ref: '#/components/schemas/mediaType' + libraryItemMinified: + type: object + description: A single item on the server, like a book or podcast. Minified media format. + allOf: + - $ref : '#/components/schemas/libraryItemBase' + - type: object + properties: + media: + $ref: '#/components/schemas/mediaMinified' + parameters: + authorID: + name: id + in: path + description: Author ID + required: true + schema: + $ref: '#/components/schemas/authorId' + authorInclude: + name: include + in: query + 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. + required: false + schema: + type: string + example: "items" + examples: + empty: + summary: Do not return library items + value: "" + itemOnly: + summary: Only return library items + value: "items" + itemsAndSeries: + summary: Return library items and series + value: "items,series" + authorLibraryId: + name: library + in: query + description: The ID of the library to to include filter included items from. + required: false + schema: + $ref: '#/components/schemas/libraryId' + asin: + name: asin + in: query + description: The Audible Identifier (ASIN). + required: false + schema: + $ref: '#/components/schemas/authorASIN' + authorSearchName: + name: q + in: query + description: The name of the author to use for searching. + required: false + schema: + type: string + example: Terry Goodkind + authorName: + name: name + in: query + description: The new name of the author. + required: false + schema: + $ref: '#/components/schemas/authorName' + authorDescription: + name: description + in: query + description: The new description of the author. + required: false + schema: + type: string + nullable: true + example: Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork, ‘The Sword of Truth’. He has written 30+ major, bestselling novels, has been published in more than 20 languages world-wide, and has sold more than 26 Million books. ‘The Sword of Truth’ is a revered literary tour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. + authorImagePath: + name: imagePath + in: query + description: The new absolute path for the author image. + required: false + schema: + type: string + nullable: true + example: /metadata/authors/aut_z3leimgybl7uf3y4ab.jpg + imageURL: + name: url + in: query + description: The URL of the image to add to the server + required: true + schema: + type: string + format: uri + example: https://images-na.ssl-images-amazon.com/images/I/51NoQTm33OL.__01_SX120_CR0,0,120,120__.jpg + imageWidth: + name: width + in: query + description: The requested width of image in pixels. + schema: + type: integer + default: 400 + example: 400 + example: 400 + imageHeight: + name: height + in: query + description: The requested height of image in pixels. If `null`, the height is scaled to maintain aspect ratio based on the requested width. + schema: + type: integer + nullable: true + default: null + example: 600 + examples: + scaleHeight: + summary: Scale height with width + value: null + fixedHeight: + summary: Force height of image + value: 600 + imageFormat: + name: format + in: query + description: The requested output format. + schema: + type: string + default: jpeg + example: webp + imageRaw: + name: raw + in: query + description: Return the raw image without scaling if true. + schema: + type: boolean + default: false + responses: + ok200: + description: OK + author404: + description: Author not found. + content: + text/html: + schema: + type: string + example: Not found + paths: + /api/authors/{id}: + get: + operationId: getAuthorByID + summary: Get a single author by ID on server + tags: + - Authors + parameters: + - $ref: '#/components/parameters/authorID' + - $ref: '#/components/parameters/authorInclude' + - $ref: '#/components/parameters/authorLibraryId' + responses: + 200: + description: getAuthorByID OK + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/author' + - $ref: '#/components/schemas/authorWithItems' + - $ref: '#/components/schemas/authorWithSeries' + 404: + $ref: '#/components/responses/author404' + /api/authors/{id}: + patch: + operationId: updateAuthorByID + summary: Update a single author by ID on server. This endpoint will merge two authors if the new author name matches another author in the database. + tags: + - Authors + parameters: + - $ref: '#/components/parameters/authorID' + - $ref: '#/components/parameters/asin' + - $ref: '#/components/parameters/authorName' + - $ref: '#/components/parameters/authorDescription' + - $ref: '#/components/parameters/authorImagePath' + responses: + 200: + description: updateAuthorByID OK + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/author' + - $ref: '#/components/schemas/authorUpdated' + - type: object + properties: + merged: + description: Will only exist and be `true` if the author was merged with another author + type: boolean + nullable: true + 404: + $ref: '#/components/responses/author404' + /api/authors/{id}: + delete: + operationId: deleteAuthorByID + summary: Delete a single author by ID on server and remove author from all books. + tags: + - Authors + parameters: + - $ref: '#/components/parameters/authorID' + responses: + 200: + $ref: '#/components/responses/ok200' + 404: + $ref: '#/components/responses/author404' + /api/authors/{id}/image: + post: + operationId: setAuthorImageByID + summary: Set an author image using a provided URL. + tags: + - Authors + parameters: + - $ref: '#/components/parameters/authorID' + - $ref: '#/components/parameters/imageURL' + responses: + 200: + description: setAuthorImageByID OK + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/author' + 404: + $ref: '#/components/responses/author404' + /api/authors/{id}/image: + delete: + operationId: deleteAuthorImageByID + summary: Delete an author image from the server and remove the image from the database. + tags: + - Authors + parameters: + - $ref: '#/components/parameters/authorID' + responses: + 200: + $ref: '#/components/responses/ok200' + 404: + $ref: '#/components/responses/author404' + /api/authors/{id}/match: + post: + operationId: matchAuthorByID + summary: 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 + parameters: + - $ref: '#/components/parameters/authorID' + - $ref: '#/components/parameters/asin' + - $ref: '#/components/parameters/authorSearchName' + responses: + 200: + description: matchAuthorByID OK + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/author' + - $ref: '#/components/schemas/authorUpdated' + 404: + $ref: '#/components/responses/author404' + /api/authors/{id}/image: + patch: + operationId: getAuthorImageByID + summary: Return the author image by author ID. + tags: + - Authors + parameters: + - $ref: '#/components/parameters/authorID' + - $ref: '#/components/parameters/imageWidth' + - $ref: '#/components/parameters/imageHeight' + - $ref: '#/components/parameters/imageFormat' + - $ref: '#/components/parameters/imageRaw' + responses: + 200: + description: getAuthorImageByID OK + content: + image/*: + schema: + type: string + format: binary + 404: + $ref: '#/components/responses/author404' +tags: + - name: Authors + description: Author endpoints From c7ac12a67a3b3bf9fbd4b64b333d1f8563bb4434 Mon Sep 17 00:00:00 2001 From: Nicholas Wallace Date: Sun, 31 Mar 2024 22:47:14 +0000 Subject: [PATCH 02/39] Split schema to sub files --- docs/controllers/AuthorController.yaml | 139 +++ docs/objects/Folder.yaml | 21 + docs/objects/Library.yaml | 12 + docs/objects/LibraryItem.yaml | 66 ++ docs/objects/entities/Author.yaml | 104 ++ docs/objects/entities/Series.yaml | 11 + docs/objects/files/AudioFile.yaml | 94 ++ docs/objects/mediaTypes/Book.yaml | 70 ++ docs/objects/mediaTypes/media.yaml | 10 + docs/objects/metadata/AudioMetaTags.yaml | 103 ++ docs/objects/metadata/BookMetadata.yaml | 126 +++ docs/objects/metadata/FileMetadata.yaml | 39 + docs/schemas.yaml | 33 + docs/spec.yaml | 1093 +++------------------- 14 files changed, 964 insertions(+), 957 deletions(-) create mode 100644 docs/controllers/AuthorController.yaml create mode 100644 docs/objects/Folder.yaml create mode 100644 docs/objects/Library.yaml create mode 100644 docs/objects/LibraryItem.yaml create mode 100644 docs/objects/entities/Author.yaml create mode 100644 docs/objects/entities/Series.yaml create mode 100644 docs/objects/files/AudioFile.yaml create mode 100644 docs/objects/mediaTypes/Book.yaml create mode 100644 docs/objects/mediaTypes/media.yaml create mode 100644 docs/objects/metadata/AudioMetaTags.yaml create mode 100644 docs/objects/metadata/BookMetadata.yaml create mode 100644 docs/objects/metadata/FileMetadata.yaml create mode 100644 docs/schemas.yaml diff --git a/docs/controllers/AuthorController.yaml b/docs/controllers/AuthorController.yaml new file mode 100644 index 00000000..4e576af7 --- /dev/null +++ b/docs/controllers/AuthorController.yaml @@ -0,0 +1,139 @@ +components: + schemas: + authorUpdated: + description: Whether the author was updated without errors. Will not exist if author was merged. + type: boolean + nullable: true + parameters: + authorID: + name: id + in: path + description: Author ID + required: true + schema: + $ref: '../objects/entities/Author.yaml#/components/schemas/authorId' + authorInclude: + name: include + in: query + 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. + required: false + schema: + type: string + example: "items" + examples: + empty: + summary: Do not return library items + value: "" + itemOnly: + summary: Only return library items + value: "items" + itemsAndSeries: + summary: Return library items and series + value: "items,series" + authorLibraryId: + name: library + in: query + description: The ID of the library to to include filter included items from. + required: false + schema: + $ref: '../objects/Library.yaml#/components/schemas/libraryId' + asin: + name: asin + in: query + description: The Audible Identifier (ASIN). + required: false + schema: + $ref: '../objects/entities/Author.yaml#/components/schemas/authorASIN' + authorSearchName: + name: q + in: query + description: The name of the author to use for searching. + required: false + schema: + type: string + example: Terry Goodkind + authorName: + name: name + in: query + description: The new name of the author. + required: false + schema: + $ref: '../objects/entities/Author.yaml#/components/schemas/authorName' + authorDescription: + name: description + in: query + description: The new description of the author. + required: false + schema: + type: string + nullable: true + example: Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork, ‘The Sword of Truth’. He has written 30+ major, bestselling novels, has been published in more than 20 languages world-wide, and has sold more than 26 Million books. ‘The Sword of Truth’ is a revered literary tour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. + authorImagePath: + name: imagePath + in: query + description: The new absolute path for the author image. + required: false + schema: + type: string + nullable: true + example: /metadata/authors/aut_z3leimgybl7uf3y4ab.jpg + imageURL: + name: url + in: query + description: The URL of the image to add to the server + required: true + schema: + type: string + format: uri + example: https://images-na.ssl-images-amazon.com/images/I/51NoQTm33OL.__01_SX120_CR0,0,120,120__.jpg + imageWidth: + name: width + in: query + description: The requested width of image in pixels. + schema: + type: integer + default: 400 + example: 400 + example: 400 + imageHeight: + name: height + in: query + description: The requested height of image in pixels. If `null`, the height is scaled to maintain aspect ratio based on the requested width. + schema: + type: integer + nullable: true + default: null + example: 600 + examples: + scaleHeight: + summary: Scale height with width + value: null + fixedHeight: + summary: Force height of image + value: 600 + imageFormat: + name: format + in: query + description: The requested output format. + schema: + type: string + default: jpeg + example: webp + imageRaw: + name: raw + in: query + description: Return the raw image without scaling if true. + schema: + type: boolean + default: false + responses: + author404: + description: Author not found. + content: + text/html: + schema: + type: string + example: Not found +tags: + - name: Authors + description: Author endpoints diff --git a/docs/objects/Folder.yaml b/docs/objects/Folder.yaml new file mode 100644 index 00000000..5c477b35 --- /dev/null +++ b/docs/objects/Folder.yaml @@ -0,0 +1,21 @@ +components: + schemas: + folderId: + type: string + description: The ID of the folder. + format: uuid + example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b + folder: + type: object + description: Folder used in library + properties: + id: + $ref: '#/components/schemas/folderId' + fullPath: + description: The path on the server for the folder. (Read Only) + type: string + example: /podcasts + libraryId: + $ref: './Library.yaml#/components/schemas/libraryId' + addedAt: + $ref: '../schemas.yaml#/components/schemas/addedAt' diff --git a/docs/objects/Library.yaml b/docs/objects/Library.yaml new file mode 100644 index 00000000..7d2a7833 --- /dev/null +++ b/docs/objects/Library.yaml @@ -0,0 +1,12 @@ +components: + schemas: + oldLibraryId: + type: string + description: The ID of the libraries created on server version 2.2.23 and before. + format: "lib_[a-z0-9]{18}" + example: lib_o78uaoeuh78h6aoeif + libraryId: + type: string + description: The ID of the library. + format: uuid + example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b diff --git a/docs/objects/LibraryItem.yaml b/docs/objects/LibraryItem.yaml new file mode 100644 index 00000000..5d2f2b3d --- /dev/null +++ b/docs/objects/LibraryItem.yaml @@ -0,0 +1,66 @@ +components: + schemas: + oldLibraryItemId: + description: The ID of library items on server version 2.2.23 and before. + type: string + nullable: true + format: "li_[a-z0-9]{18}" + example: li_o78uaoeuh78h6aoeif + libraryItemId: + type: string + description: The ID of library items after 2.3.0. + format: uuid + example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b + libraryItemBase: + type: object + description: Base library item schema + properties: + id: + $ref: '#/components/schemas/libraryItemId' + oldLibraryItemId: + $ref: '#/components/schemas/oldLibraryItemId' + ino: + $ref: '../schemas.yaml#/components/schemas/inode' + libraryId: + $ref: './Library.yaml#/components/schemas/libraryId' + folderId: + $ref: './Folder.yaml#/components/schemas/folderId' + path: + description: The path of the library item on the server. + type: string + relPath: + description: The path, relative to the library folder, of the library item. + type: string + isFile: + description: Whether the library item is a single file in the root of the library folder. + type: boolean + mtimeMs: + description: The time (in ms since POSIX epoch) when the library item was last modified on disk. + type: integer + ctimeMs: + description: The time (in ms since POSIX epoch) when the library item status was changed on disk. + type: integer + birthtimeMs: + description: The time (in ms since POSIX epoch) when the library item was created on disk. Will be 0 if unknown. + type: integer + addedAt: + $ref: '../schemas.yaml#/components/schemas/addedAt' + updatedAt: + $ref: '../schemas.yaml#/components/schemas/updatedAt' + isMissing: + description: Whether the library item was scanned and no longer exists. + type: boolean + isInvalid: + description: Whether the library item was scanned and no longer has media files. + type: boolean + mediaType: + $ref: './mediaTypes/media.yaml#/components/schemas/mediaType' + libraryItemMinified: + type: object + description: A single item on the server, like a book or podcast. Minified media format. + allOf: + - $ref : '#/components/schemas/libraryItemBase' + - type: object + properties: + media: + $ref: './mediaTypes/media.yaml#/components/schemas/mediaMinified' diff --git a/docs/objects/entities/Author.yaml b/docs/objects/entities/Author.yaml new file mode 100644 index 00000000..d2b173fc --- /dev/null +++ b/docs/objects/entities/Author.yaml @@ -0,0 +1,104 @@ +components: + schemas: + authorId: + type: string + description: The ID of the author. + format: uuid + example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b + authorASIN: + type: string + description: The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier. + nullable: true + example: B000APZOQA + authorName: + description: The name of the author. + type: string + example: Terry Goodkind + authorSeries: + type: object + description: Series and the included library items that an author has written. + properties: + id: + $ref: './Series.yaml#/components/schemas/seriesId' + name: + $ref: './Series.yaml#/components/schemas/seriesName' + items: + description: The items in the series. Each library item's media's metadata will have a `series` attribute, a `Series Sequence`, which is the matching series. + type: array + items: + ref: '../LibraryItem.yaml#/components/schemas/libraryItemMinified' + author: + description: An author object which includes a description and image path. + type: object + properties: + id: + $ref: '#/components/schemas/authorId' + asin: + $ref: '#/components/schemas/authorASIN' + name: + $ref: '#/components/schemas/authorName' + description: + description: A description of the author. Will be null if there is none. + type: string + nullable: true + example: | + Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork, + ‘The Sword of Truth’. He has written 30+ major, bestselling novels, has been published in more than 20 + languages world-wide, and has sold more than 26 Million books. ‘The Sword of Truth’ is a revered literary + tour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. Terry Goodkind's + brilliant books are character-driven stories, with a focus on the complexity of the human psyche. Goodkind + has an uncanny grasp for crafting compelling stories about people like you and me, trapped in terrifying + situations. + imagePath: + description: The absolute path for the author image located in the `metadata/` directory. Will be null if there is no image. + type: string + nullable: true + example: /metadata/authors/aut_bxxbyjiptmgb56yzoz.jpg + addedAt: + $ref: '../../schemas.yaml#/components/schemas/addedAt' + updatedAt: + $ref: '../../schemas.yaml#/components/schemas/updatedAt' + authorWithItems: + type: object + description: The author schema with an array of items they are associated with. + allOf: + - $ref: '#/components/schemas/author' + - type: object + properties: + libraryItems: + description: The items associated with the author + type: string + type: array + items: + $ref: '../LibraryItem.yaml#/components/schemas/libraryItemMinified' + authorWithSeries: + type: object + description: The author schema with an array of items and series they are associated with. + allOf: + - $ref: '#/components/schemas/authorWithItems' + - type: object + properties: + series: + description: The series associated with the author + type: array + items: + $ref: '#/components/schemas/authorSeries' + authorMinified: + type: object + description: Minified author object which only contains the author name and ID. + properties: + id: + $ref: '#/components/schemas/authorId' + name: + $ref: '#/components/schemas/authorName' + authorExpanded: + type: object + description: The author schema with the total number of books in the library. + allOf: + - $ref: '#/components/schemas/author' + - type: object + properties: + numBooks: + description: The number of books associated with the author in the library. + type: integer + example: 1 \ No newline at end of file diff --git a/docs/objects/entities/Series.yaml b/docs/objects/entities/Series.yaml new file mode 100644 index 00000000..af818477 --- /dev/null +++ b/docs/objects/entities/Series.yaml @@ -0,0 +1,11 @@ +components: + schemas: + seriesId: + type: string + description: The ID of the series. + format: uuid + example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b + seriesName: + description: The name of the series. + type: string + example: Sword of Truth \ No newline at end of file diff --git a/docs/objects/files/AudioFile.yaml b/docs/objects/files/AudioFile.yaml new file mode 100644 index 00000000..06a9c80c --- /dev/null +++ b/docs/objects/files/AudioFile.yaml @@ -0,0 +1,94 @@ +components: + schemas: + audioFile: + type: object + description: An audio file for a book. Includes audio metadata and track numbers. + properties: + index: + description: The index of the audio file. + type: integer + example: 1 + ino: + $ref: '../../schemas.yaml#/components/schemas/inode' + metadata: + $ref: '../metadata/FileMetadata.yaml#/components/schemas/fileMetadata' + addedAt: + $ref: '../../schemas.yaml#/components/schemas/addedAt' + updatedAt: + $ref: '../../schemas.yaml#/components/schemas/updatedAt' + trackNumFromMeta: + description: The track number of the audio file as pulled from the file's metadata. Will be null if unknown. + type: integer + nullable: true + example: 1 + discNumFromMeta: + description: The disc number of the audio file as pulled from the file's metadata. Will be null if unknown. + type: string + nullable: true + trackNumFromFilename: + description: The track number of the audio file as determined from the file's name. Will be null if unknown. + type: integer + nullable: true + example: 1 + discNumFromFilename: + description: The disc number of the audio file as determined from the file's name. Will be null if unknown. + type: string + nullable: true + manuallyVerified: + description: Whether the audio file has been manually verified by a user. + type: boolean + invalid: + description: Whether the audio file is missing from the server. + type: boolean + exclude: + description: Whether the audio file has been marked for exclusion. + type: boolean + error: + description: Any error with the audio file. Will be null if there is none. + type: string + nullable: true + format: + description: The format of the audio file. + type: string + example: MP2/3 (MPEG audio layer 2/3) + duration: + $ref: '#/components/schemas/durationSec' + bitRate: + description: The bit rate (in bit/s) of the audio file. + type: integer + example: 64000 + language: + description: The language of the audio file. + type: string + nullable: true + codec: + description: The codec of the audio file. + type: string + example: mp3 + timeBase: + description: The time base of the audio file. + type: string + example: 1/14112000 + channels: + description: The number of channels the audio file has. + type: integer + example: 2 + channelLayout: + description: The layout of the audio file's channels. + type: string + example: stereo + chapters: + description: If the audio file is part of an audiobook, the chapters the file contains. + type: array + items: + $ref: '../metadata/BookMetadata.yaml#/components/schemas/bookChapter' + embeddedCoverArt: + description: The type of embedded cover art in the audio file. Will be null if none exists. + type: string + nullable: true + metaTags: + $ref: '../metadata/AudioMetaTags.yaml#/components/schemas/audioMetaTags' + mimeType: + description: The MIME type of the audio file. + type: string + example: audio/mpeg diff --git a/docs/objects/mediaTypes/Book.yaml b/docs/objects/mediaTypes/Book.yaml new file mode 100644 index 00000000..44f3552e --- /dev/null +++ b/docs/objects/mediaTypes/Book.yaml @@ -0,0 +1,70 @@ +components: + schemas: + bookCoverPath: + description: The absolute path on the server of the cover file. Will be null if there is no cover. + type: string + nullable: true + example: /audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg + bookBase: + type: object + description: Base book schema + properties: + libraryItemId: + $ref: '../LibraryItem.yaml#/components/schemas/libraryItemId' + coverPath: + $ref: '#/components/schemas/bookCoverPath' + tags: + $ref: '../../schemas.yaml#/components/schemas/tags' + audioFiles: + type: array + items: + $ref: '#/components/schemas/audioFile' + chapters: + type: array + items: + $ref: '#/components/schemas/bookChapter' + missingParts: + description: Any parts missing from the book by track index. + type: array + items: + type: integer + ebookFile: + $ref: '#/components/schemas/ebookFile' + bookMinified: + type: object + description: Minified book schema. Does not depend on `bookBase` because there's pretty much no overlap. + properties: + metadata: + $ref: '../metadata/BookMetadata.yaml#/components/schemas/bookMetadataMinified' + coverPath: + $ref: '#/components/schemas/bookCoverPath' + tags: + $ref: '../../schemas.yaml#/components/schemas/tags' + numTracks: + description: The number of tracks the book's audio files have. + type: integer + example: 1 + numAudioFiles: + description: The number of audio files the book has. + type: integer + example: 1 + numChapters: + description: The number of chapters the book has. + type: integer + example: 1 + numMissingParts: + description: The total number of missing parts the book has. + type: integer + example: 0 + numInvalidAudioFiles: + description: The number of invalid audio files the book has. + type: integer + example: 0 + duration: + $ref: '../../schemas.yaml#/components/schemas/durationSec' + size: + $ref: '../../schemas.yaml#/components/schemas/size' + ebookFormat: + description: The format of ebook of the book. Will be null if the book is an audiobook. + type: string + nullable: true diff --git a/docs/objects/mediaTypes/media.yaml b/docs/objects/mediaTypes/media.yaml new file mode 100644 index 00000000..a7d4b08e --- /dev/null +++ b/docs/objects/mediaTypes/media.yaml @@ -0,0 +1,10 @@ +components: + schemas: + mediaType: + type: string + description: The type of media, will be book or podcast. + enum: [book, podcast] + mediaMinified: + description: The minified media of the library item. + oneOf: + - $ref: './Book.yaml#/components/schemas/bookMinified' diff --git a/docs/objects/metadata/AudioMetaTags.yaml b/docs/objects/metadata/AudioMetaTags.yaml new file mode 100644 index 00000000..ef4058a8 --- /dev/null +++ b/docs/objects/metadata/AudioMetaTags.yaml @@ -0,0 +1,103 @@ +components: + schemas: + audioMetaTags: + description: ID3 metadata tags pulled from the audio file on import. Only non-null tags will be returned in requests. + type: object + properties: + tagAlbum: + type: string + nullable: true + example: SOT Bk01 + tagArtist: + type: string + nullable: true + example: Terry Goodkind + tagGenre: + type: string + nullable: true + example: Audiobook Fantasy + tagTitle: + type: string + nullable: true + example: Wizards First Rule 01 + tagSeries: + type: string + nullable: true + tagSeriesPart: + type: string + nullable: true + tagTrack: + type: string + nullable: true + example: 01/20 + tagDisc: + type: string + nullable: true + tagSubtitle: + type: string + nullable: true + tagAlbumArtist: + type: string + nullable: true + example: Terry Goodkind + tagDate: + type: string + nullable: true + tagComposer: + type: string + nullable: true + example: Terry Goodkind + tagPublisher: + type: string + nullable: true + tagComment: + type: string + nullable: true + tagDescription: + type: string + nullable: true + tagEncoder: + type: string + nullable: true + tagEncodedBy: + type: string + nullable: true + tagIsbn: + type: string + nullable: true + tagLanguage: + type: string + nullable: true + tagASIN: + type: string + nullable: true + tagOverdriveMediaMarker: + type: string + nullable: true + tagOriginalYear: + type: string + nullable: true + tagReleaseCountry: + type: string + nullable: true + tagReleaseType: + type: string + nullable: true + tagReleaseStatus: + type: string + nullable: true + tagISRC: + type: string + nullable: true + tagMusicBrainzTrackId: + type: string + nullable: true + tagMusicBrainzAlbumId: + type: string + nullable: true + tagMusicBrainzAlbumArtistId: + type: string + nullable: true + tagMusicBrainzArtistId: + type: string + nullable: true diff --git a/docs/objects/metadata/BookMetadata.yaml b/docs/objects/metadata/BookMetadata.yaml new file mode 100644 index 00000000..faa054ac --- /dev/null +++ b/docs/objects/metadata/BookMetadata.yaml @@ -0,0 +1,126 @@ +components: + schemas: + narrators: + description: The narrators of the audiobook. + type: array + items: + type: string + example: Sam Tsoutsouvas + bookMetadataBase: + type: object + description: The base book metadata object for minified, normal, and extended schemas to inherit from. + properties: + title: + description: The title of the book. Will be null if unknown. + type: string + nullable: true + example: Wizards First Rule + subtitle: + description: The subtitle of the book. Will be null if there is no subtitle. + type: string + nullable: true + genres: + description: The genres of the book. + type: array + items: + type: string + example: ["Fantasy", "Sci-Fi", "Nonfiction: History"] + publishedYear: + description: The year the book was published. Will be null if unknown. + type: string + nullable: true + example: '2008' + publishedDate: + description: The date the book was published. Will be null if unknown. + type: string + nullable: true + publisher: + description: The publisher of the book. Will be null if unknown. + type: string + nullable: true + example: Brilliance Audio + description: + description: A description for the book. Will be null if empty. + type: string + nullable: true + example: >- + The masterpiece that started Terry Goodkind's New York Times bestselling + epic Sword of Truth In the aftermath of the brutal murder of his father, + a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest + sanctuary seeking help...and more. His world, his very beliefs, are + shattered when ancient debts come due with thundering violence. In a + dark age it takes courage to live, and more than mere courage to + challenge those who hold dominion, Richard and Kahlan must take up that + challenge or become the next victims. Beyond awaits a bewitching land + where even the best of their hearts could betray them. Yet, Richard + fears nothing so much as what secrets his sword might reveal about his + own soul. Falling in love would destroy them - for reasons Richard can't + imagine and Kahlan dare not say. In their darkest hour, hunted + relentlessly, tormented by treachery and loss, Kahlan calls upon Richard + to reach beyond his sword - to invoke within himself something more + noble. Neither knows that the rules of battle have just changed...or + that their time has run out. Wizard's First Rule is the beginning. One + book. One Rule. Witness the birth of a legend. + isbn: + description: The ISBN of the book. Will be null if unknown. + type: string + nullable: true + asin: + description: The ASIN of the book. Will be null if unknown. + type: string + nullable: true + example: B002V0QK4C + language: + description: The language of the book. Will be null if unknown. + type: string + nullable: true + explicit: + description: Whether the book has been marked as explicit. + type: boolean + example: false + bookMetadataMinified: + type: object + description: The minified metadata for a book in the database. + allOf: + - $ref : '#/components/schemas/bookMetadataBase' + - type: object + properties: + titleIgnorePrefix: + description: The title of the book with any prefix moved to the end. + type: string + authorName: + description: The name of the book's author(s). + type: string + example: Terry Goodkind + authorNameLF: + description: The name of the book's author(s) with last names first. + type: string + example: Goodkind, Terry + narratorName: + description: The name of the audiobook's narrator(s). + type: string + example: Sam Tsoutsouvas + seriesName: + description: The name of the book's series. + type: string + example: Sword of Truth + bookChapter: + type: object + description: A book chapter. Includes the title and timestamps. + properties: + id: + description: The ID of the book chapter. + type: integer + example: 0 + start: + description: When in the book (in seconds) the chapter starts. + type: integer + example: 0 + end: + description: When in the book (in seconds) the chapter ends. + type: number + example: 6004.6675 + title: + description: The title of the chapter. + type: string + example: Wizards First Rule 01 Chapter 1 diff --git a/docs/objects/metadata/FileMetadata.yaml b/docs/objects/metadata/FileMetadata.yaml new file mode 100644 index 00000000..13e15e8b --- /dev/null +++ b/docs/objects/metadata/FileMetadata.yaml @@ -0,0 +1,39 @@ +components: + schemas: + fileMetadata: + type: object + description: The metadata for a file, including the path, size, and unix timestamps of the file. + nullable: true + properties: + filename: + description: The filename of the file. + type: string + example: Wizards First Rule 01.mp3 + ext: + description: The file extension of the file. + type: string + example: .mp3 + path: + description: The absolute path on the server of the file. + type: string + example: >- + /audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry + Goodkind - SOT Bk01 - Wizards First Rule 01.mp3 + relPath: + description: The path of the file, relative to the book's or podcast's folder. + type: string + example: Wizards First Rule 01.mp3 + size: + $ref: '../../schemas.yaml#/components/schemas/size' + mtimeMs: + description: The time (in ms since POSIX epoch) when the file was last modified on disk. + type: integer + example: 1632223180278 + ctimeMs: + description: The time (in ms since POSIX epoch) when the file status was changed on disk. + type: integer + example: 1645978261001 + birthtimeMs: + description: The time (in ms since POSIX epoch) when the file was created on disk. Will be 0 if unknown. + type: integer + example: 0 diff --git a/docs/schemas.yaml b/docs/schemas.yaml new file mode 100644 index 00000000..de506d46 --- /dev/null +++ b/docs/schemas.yaml @@ -0,0 +1,33 @@ +components: + schemas: + addedAt: + type: integer + description: The time (in ms since POSIX epoch) when added to the server. + example: 1633522963509 + createdAt: + type: integer + description: The time (in ms since POSIX epoch) when was created. + example: 1633522963509 + updatedAt: + type: integer + description: The time (in ms since POSIX epoch) when last updated. + example: 1633522963509 + size: + description: The total size (in bytes) of the item or file. + type: integer + example: 268824228 + durationSec: + description: The total length (in seconds) of the item or file. + type: number + example: 33854.905 + tags: + description: Tags applied to items. + type: array + items: + type: string + example: ["To Be Read", "Genre: Nonfiction"] + inode: + description: The inode of the item in the file system. + type: string + format: "[0-9]*" + example: '649644248522215260' \ No newline at end of file diff --git a/docs/spec.yaml b/docs/spec.yaml index dfe95b69..fdab0125 100644 --- a/docs/spec.yaml +++ b/docs/spec.yaml @@ -3,970 +3,149 @@ info: title: Audiobookshelf API version: 0.1.0 description: Audiobookshelf API with autogenerated OpenAPI doc - servers: - url: http://localhost:3000 description: Development server - components: - schemas: - mediaType: - type: string - description: The type of media, will be book or podcast. - enum: [book, podcast] - mediaMinified: - description: The minified media of the library item. - oneOf: - - $ref: '#/components/schemas/bookMinified' - bookCoverPath: - description: The absolute path on the server of the cover file. Will be null if there is no cover. - type: string - nullable: true - example: /audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg - bookBase: - type: object - description: Base book schema - properties: - libraryItemId: - $ref: '#/components/schemas/libraryItemId' - coverPath: - $ref: '#/components/schemas/bookCoverPath' - tags: - $ref: '#/components/schemas/tags' - audioFiles: - type: array - items: - $ref: '#/components/schemas/audioFile' - chapters: - type: array - items: - $ref: '#/components/schemas/bookChapter' - missingParts: - description: Any parts missing from the book by track index. - type: array - items: - type: integer - ebookFile: - $ref: '#/components/schemas/ebookFile' - bookMinified: - type: object - description: Minified book schema. Does not depend on `bookBase` because there's pretty much no overlap. - properties: - metadata: - $ref: '#/components/schemas/bookMetadataMinified' - coverPath: - $ref: '#/components/schemas/bookCoverPath' - tags: - $ref: '#/components/schemas/tags' - numTracks: - description: The number of tracks the book's audio files have. - type: integer - example: 1 - numAudioFiles: - description: The number of audio files the book has. - type: integer - example: 1 - numChapters: - description: The number of chapters the book has. - type: integer - example: 1 - numMissingParts: - description: The total number of missing parts the book has. - type: integer - example: 0 - numInvalidAudioFiles: - description: The number of invalid audio files the book has. - type: integer - example: 0 - duration: - $ref: '#/components/schemas/durationSec' - size: - $ref: '#/components/schemas/size' - ebookFormat: - description: The format of ebook of the book. Will be null if the book is an audiobook. - type: string - nullable: true - narrators: - description: The narrators of the audiobook. - type: array - items: - type: string - example: Sam Tsoutsouvas - bookMetadataBase: - type: object - description: The base book metadata object for minified, normal, and extended schemas to inherit from. - properties: - title: - description: The title of the book. Will be null if unknown. - type: string - nullable: true - example: Wizards First Rule - subtitle: - description: The subtitle of the book. Will be null if there is no subtitle. - type: string - nullable: true - genres: - description: The genres of the book. - type: array - items: - type: string - example: ["Fantasy", "Sci-Fi", "Nonfiction: History"] - publishedYear: - description: The year the book was published. Will be null if unknown. - type: string - nullable: true - example: '2008' - publishedDate: - description: The date the book was published. Will be null if unknown. - type: string - nullable: true - publisher: - description: The publisher of the book. Will be null if unknown. - type: string - nullable: true - example: Brilliance Audio - description: - description: A description for the book. Will be null if empty. - type: string - nullable: true - example: >- - The masterpiece that started Terry Goodkind's New York Times bestselling - epic Sword of Truth In the aftermath of the brutal murder of his father, - a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest - sanctuary seeking help...and more. His world, his very beliefs, are - shattered when ancient debts come due with thundering violence. In a - dark age it takes courage to live, and more than mere courage to - challenge those who hold dominion, Richard and Kahlan must take up that - challenge or become the next victims. Beyond awaits a bewitching land - where even the best of their hearts could betray them. Yet, Richard - fears nothing so much as what secrets his sword might reveal about his - own soul. Falling in love would destroy them - for reasons Richard can't - imagine and Kahlan dare not say. In their darkest hour, hunted - relentlessly, tormented by treachery and loss, Kahlan calls upon Richard - to reach beyond his sword - to invoke within himself something more - noble. Neither knows that the rules of battle have just changed...or - that their time has run out. Wizard's First Rule is the beginning. One - book. One Rule. Witness the birth of a legend. - isbn: - description: The ISBN of the book. Will be null if unknown. - type: string - nullable: true - asin: - description: The ASIN of the book. Will be null if unknown. - type: string - nullable: true - example: B002V0QK4C - language: - description: The language of the book. Will be null if unknown. - type: string - nullable: true - explicit: - description: Whether the book has been marked as explicit. - type: boolean - example: false - bookMetadataMinified: - type: object - description: The minified metadata for a book in the database. - allOf: - - $ref : '#/components/schemas/bookMetadataBase' - - type: object - properties: - titleIgnorePrefix: - description: The title of the book with any prefix moved to the end. - type: string - authorName: - description: The name of the book's author(s). - type: string - example: Terry Goodkind - authorNameLF: - description: The name of the book's author(s) with last names first. - type: string - example: Goodkind, Terry - narratorName: - description: The name of the audiobook's narrator(s). - type: string - example: Sam Tsoutsouvas - seriesName: - description: The name of the book's series. - type: string - example: Sword of Truth - bookChapter: - type: object - description: A book chapter. Includes the title and timestamps. - properties: - id: - description: The ID of the book chapter. - type: integer - example: 0 - start: - description: When in the book (in seconds) the chapter starts. - type: integer - example: 0 - end: - description: When in the book (in seconds) the chapter ends. - type: number - example: 6004.6675 - title: - description: The title of the chapter. - type: string - example: Wizards First Rule 01 Chapter 1 - audioFile: - type: object - description: An audio file for a book. Includes audio metadata and track numbers. - properties: - index: - description: The index of the audio file. - type: integer - example: 1 - ino: - $ref: '#/components/schemas/inode' - metadata: - $ref: '#/components/schemas/fileMetadata' - addedAt: - $ref: '#/components/schemas/addedAt' - updatedAt: - $ref: '#/components/schemas/updatedAt' - trackNumFromMeta: - description: The track number of the audio file as pulled from the file's metadata. Will be null if unknown. - type: integer - nullable: true - example: 1 - discNumFromMeta: - description: The disc number of the audio file as pulled from the file's metadata. Will be null if unknown. - type: string - nullable: true - trackNumFromFilename: - description: The track number of the audio file as determined from the file's name. Will be null if unknown. - type: integer - nullable: true - example: 1 - discNumFromFilename: - description: The disc number of the audio file as determined from the file's name. Will be null if unknown. - type: string - nullable: true - manuallyVerified: - description: Whether the audio file has been manually verified by a user. - type: boolean - invalid: - description: Whether the audio file is missing from the server. - type: boolean - exclude: - description: Whether the audio file has been marked for exclusion. - type: boolean - error: - description: Any error with the audio file. Will be null if there is none. - type: string - nullable: true - format: - description: The format of the audio file. - type: string - example: MP2/3 (MPEG audio layer 2/3) - duration: - $ref: '#/components/schemas/durationSec' - bitRate: - description: The bit rate (in bit/s) of the audio file. - type: integer - example: 64000 - language: - description: The language of the audio file. - type: string - nullable: true - codec: - description: The codec of the audio file. - type: string - example: mp3 - timeBase: - description: The time base of the audio file. - type: string - example: 1/14112000 - channels: - description: The number of channels the audio file has. - type: integer - example: 2 - channelLayout: - description: The layout of the audio file's channels. - type: string - example: stereo - chapters: - description: If the audio file is part of an audiobook, the chapters the file contains. - type: array - items: - $ref: '#/components/schemas/bookChapter' - embeddedCoverArt: - description: The type of embedded cover art in the audio file. Will be null if none exists. - type: string - nullable: true - metaTags: - $ref: '#/components/schemas/audioMetaTags' - mimeType: - description: The MIME type of the audio file. - type: string - example: audio/mpeg - ebookFile: - type: object - description: An ebook file for a library item. - nullable: true - properties: - ino: - $ref: '#/components/schemas/inode' - metadata: - $ref: '#/components/schemas/fileMetadata' - ebookFormat: - description: The ebook format of the ebook file. - type: string - example: epub - addedAt: - $ref: '#/components/schemas/addedAt' - updatedAt: - $ref: '#/components/schemas/updatedAt' - fileMetadata: - type: object - description: The metadata for a file, including the path, size, and unix timestamps of the file. - nullable: true - properties: - filename: - description: The filename of the file. - type: string - example: Wizards First Rule 01.mp3 - ext: - description: The file extension of the file. - type: string - example: .mp3 - path: - description: The absolute path on the server of the file. - type: string - example: >- - /audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry - Goodkind - SOT Bk01 - Wizards First Rule 01.mp3 - relPath: - description: The path of the file, relative to the book's or podcast's folder. - type: string - example: Wizards First Rule 01.mp3 - size: - $ref: '#/components/schemas/size' - mtimeMs: - description: The time (in ms since POSIX epoch) when the file was last modified on disk. - type: integer - example: 1632223180278 - ctimeMs: - description: The time (in ms since POSIX epoch) when the file status was changed on disk. - type: integer - example: 1645978261001 - birthtimeMs: - description: The time (in ms since POSIX epoch) when the file was created on disk. Will be 0 if unknown. - type: integer - example: 0 - audioMetaTags: - description: ID3 metadata tags pulled from the audio file on import. Only non-null tags will be returned in requests. - type: object - properties: - tagAlbum: - type: string - nullable: true - example: SOT Bk01 - tagArtist: - type: string - nullable: true - example: Terry Goodkind - tagGenre: - type: string - nullable: true - example: Audiobook Fantasy - tagTitle: - type: string - nullable: true - example: Wizards First Rule 01 - tagSeries: - type: string - nullable: true - tagSeriesPart: - type: string - nullable: true - tagTrack: - type: string - nullable: true - example: 01/20 - tagDisc: - type: string - nullable: true - tagSubtitle: - type: string - nullable: true - tagAlbumArtist: - type: string - nullable: true - example: Terry Goodkind - tagDate: - type: string - nullable: true - tagComposer: - type: string - nullable: true - example: Terry Goodkind - tagPublisher: - type: string - nullable: true - tagComment: - type: string - nullable: true - tagDescription: - type: string - nullable: true - tagEncoder: - type: string - nullable: true - tagEncodedBy: - type: string - nullable: true - tagIsbn: - type: string - nullable: true - tagLanguage: - type: string - nullable: true - tagASIN: - type: string - nullable: true - tagOverdriveMediaMarker: - type: string - nullable: true - tagOriginalYear: - type: string - nullable: true - tagReleaseCountry: - type: string - nullable: true - tagReleaseType: - type: string - nullable: true - tagReleaseStatus: - type: string - nullable: true - tagISRC: - type: string - nullable: true - tagMusicBrainzTrackId: - type: string - nullable: true - tagMusicBrainzAlbumId: - type: string - nullable: true - tagMusicBrainzAlbumArtistId: - type: string - nullable: true - tagMusicBrainzArtistId: - type: string - nullable: true - addedAt: - type: integer - description: The time (in ms since POSIX epoch) when added to the server. - example: 1633522963509 - createdAt: - type: integer - description: The time (in ms since POSIX epoch) when was created. - example: 1633522963509 - updatedAt: - type: integer - description: The time (in ms since POSIX epoch) when last updated. - example: 1633522963509 - size: - description: The total size (in bytes) of the item or file. - type: integer - example: 268824228 - durationSec: - description: The total length (in seconds) of the item or file. - type: number - example: 33854.905 - tags: - description: Tags applied to items. - type: array - items: - type: string - example: ["To Be Read", "Genre: Nonfiction"] - inode: - description: The inode of the item in the file system. - type: string - format: "[0-9]*" - example: '649644248522215260' - seriesId: - type: string - description: The ID of the series. - format: uuid - example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b - seriesName: - description: The name of the series. - type: string - example: Sword of Truth - folderId: - type: string - description: The ID of the folder. - format: uuid - example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b - folder: - type: object - description: Folder used in library - properties: - id: - $ref: '#/components/schemas/folderId' - fullPath: - description: The path on the server for the folder. (Read Only) - type: string - example: /podcasts - libraryId: - $ref: '#/components/schemas/libraryId' - addedAt: - $ref: '#/components/schemas/addedAt' - authorUpdated: - description: Whether the author was updated without errors. Will not exist if author was merged. - type: boolean - nullable: true - authorId: - type: string - description: The ID of the author. - format: uuid - example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b - authorASIN: - type: string - description: The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier. - nullable: true - example: B000APZOQA - authorName: - description: The name of the author. - type: string - example: Terry Goodkind - authorSeries: - type: object - description: Series and the included library items that an author has written. - properties: - id: - $ref: '#/components/schemas/seriesId' - name: - $ref: '#/components/schemas/seriesName' - items: - description: The items in the series. Each library item's media's metadata will have a `series` attribute, a `Series Sequence`, which is the matching series. - type: array - items: - $ref: '#/components/schemas/libraryItemMinified' - author: - description: An author object which includes a description and image path. - type: object - properties: - id: - $ref: '#/components/schemas/authorId' - asin: - $ref: '#/components/schemas/authorASIN' - name: - $ref: '#/components/schemas/authorName' - description: - description: A description of the author. Will be null if there is none. - type: string - nullable: true - example: | - Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork, - ‘The Sword of Truth’. He has written 30+ major, bestselling novels, has been published in more than 20 - languages world-wide, and has sold more than 26 Million books. ‘The Sword of Truth’ is a revered literary - tour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. Terry Goodkind's - brilliant books are character-driven stories, with a focus on the complexity of the human psyche. Goodkind - has an uncanny grasp for crafting compelling stories about people like you and me, trapped in terrifying - situations. - imagePath: - description: The absolute path for the author image located in the `metadata/` directory. Will be null if there is no image. - type: string - nullable: true - example: /metadata/authors/aut_bxxbyjiptmgb56yzoz.jpg - addedAt: - $ref: '#/components/schemas/addedAt' - updatedAt: - $ref: '#/components/schemas/updatedAt' - authorWithItems: - type: object - description: The author schema with an array of items they are associated with. - allOf: - - $ref: '#/components/schemas/author' - - type: object - properties: - libraryItems: - description: The items associated with the author - type: array - items: - $ref: '#/components/schemas/libraryItemMinified' - authorWithSeries: - type: object - description: The author schema with an array of items and series they are associated with. - allOf: - - $ref: '#/components/schemas/authorWithItems' - - type: object - properties: - series: - description: The series associated with the author - type: array - items: - $ref: '#/components/schemas/authorSeries' - authorMinified: - type: object - description: Minified author object which only contains the author name and ID. - properties: - id: - $ref: '#/components/schemas/authorId' - name: - $ref: '#/components/schemas/authorName' - authorExpanded: - type: object - description: The author schema with the total number of books in the library. - allOf: - - $ref: '#/components/schemas/author' - - type: object - properties: - numBooks: - description: The number of books associated with the author in the library. - type: integer - example: 1 - oldLibraryId: - type: string - description: The ID of the libraries created on server version 2.2.23 and before. - format: "lib_[a-z0-9]{18}" - example: lib_o78uaoeuh78h6aoeif - libraryId: - type: string - description: The ID of the library. - format: uuid - example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b - oldLibraryItemId: - description: The ID of library items on server version 2.2.23 and before. - type: string - nullable: true - format: "li_[a-z0-9]{18}" - example: li_o78uaoeuh78h6aoeif - libraryItemId: - type: string - description: The ID of library items after 2.3.0. - format: uuid - example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b - libraryItemBase: - type: object - description: Base library item schema - properties: - id: - $ref: '#/components/schemas/libraryItemId' - oldLibraryItemId: - $ref: '#/components/schemas/oldLibraryItemId' - ino: - $ref: '#/components/schemas/inode' - libraryId: - $ref: '#/components/schemas/libraryId' - folderId: - $ref: '#/components/schemas/folderId' - path: - description: The path of the library item on the server. - type: string - relPath: - description: The path, relative to the library folder, of the library item. - type: string - isFile: - description: Whether the library item is a single file in the root of the library folder. - type: boolean - mtimeMs: - description: The time (in ms since POSIX epoch) when the library item was last modified on disk. - type: integer - ctimeMs: - description: The time (in ms since POSIX epoch) when the library item status was changed on disk. - type: integer - birthtimeMs: - description: The time (in ms since POSIX epoch) when the library item was created on disk. Will be 0 if unknown. - type: integer - addedAt: - $ref: '#/components/schemas/addedAt' - updatedAt: - $ref: '#/components/schemas/updatedAt' - isMissing: - description: Whether the library item was scanned and no longer exists. - type: boolean - isInvalid: - description: Whether the library item was scanned and no longer has media files. - type: boolean - mediaType: - $ref: '#/components/schemas/mediaType' - libraryItemMinified: - type: object - description: A single item on the server, like a book or podcast. Minified media format. - allOf: - - $ref : '#/components/schemas/libraryItemBase' - - type: object - properties: - media: - $ref: '#/components/schemas/mediaMinified' - parameters: - authorID: - name: id - in: path - description: Author ID - required: true - schema: - $ref: '#/components/schemas/authorId' - authorInclude: - name: include - in: query - 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. - required: false - schema: - type: string - example: "items" - examples: - empty: - summary: Do not return library items - value: "" - itemOnly: - summary: Only return library items - value: "items" - itemsAndSeries: - summary: Return library items and series - value: "items,series" - authorLibraryId: - name: library - in: query - description: The ID of the library to to include filter included items from. - required: false - schema: - $ref: '#/components/schemas/libraryId' - asin: - name: asin - in: query - description: The Audible Identifier (ASIN). - required: false - schema: - $ref: '#/components/schemas/authorASIN' - authorSearchName: - name: q - in: query - description: The name of the author to use for searching. - required: false - schema: - type: string - example: Terry Goodkind - authorName: - name: name - in: query - description: The new name of the author. - required: false - schema: - $ref: '#/components/schemas/authorName' - authorDescription: - name: description - in: query - description: The new description of the author. - required: false - schema: - type: string - nullable: true - example: Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork, ‘The Sword of Truth’. He has written 30+ major, bestselling novels, has been published in more than 20 languages world-wide, and has sold more than 26 Million books. ‘The Sword of Truth’ is a revered literary tour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. - authorImagePath: - name: imagePath - in: query - description: The new absolute path for the author image. - required: false - schema: - type: string - nullable: true - example: /metadata/authors/aut_z3leimgybl7uf3y4ab.jpg - imageURL: - name: url - in: query - description: The URL of the image to add to the server - required: true - schema: - type: string - format: uri - example: https://images-na.ssl-images-amazon.com/images/I/51NoQTm33OL.__01_SX120_CR0,0,120,120__.jpg - imageWidth: - name: width - in: query - description: The requested width of image in pixels. - schema: - type: integer - default: 400 - example: 400 - example: 400 - imageHeight: - name: height - in: query - description: The requested height of image in pixels. If `null`, the height is scaled to maintain aspect ratio based on the requested width. - schema: - type: integer - nullable: true - default: null - example: 600 - examples: - scaleHeight: - summary: Scale height with width - value: null - fixedHeight: - summary: Force height of image - value: 600 - imageFormat: - name: format - in: query - description: The requested output format. - schema: - type: string - default: jpeg - example: webp - imageRaw: - name: raw - in: query - description: Return the raw image without scaling if true. - schema: - type: boolean - default: false responses: ok200: description: OK - author404: - description: Author not found. - content: - text/html: - schema: - type: string - example: Not found - paths: - /api/authors/{id}: - get: - operationId: getAuthorByID - summary: Get a single author by ID on server - tags: - - Authors - parameters: - - $ref: '#/components/parameters/authorID' - - $ref: '#/components/parameters/authorInclude' - - $ref: '#/components/parameters/authorLibraryId' - responses: - 200: - description: getAuthorByID OK - content: - application/json: - schema: - oneOf: - - $ref: '#/components/schemas/author' - - $ref: '#/components/schemas/authorWithItems' - - $ref: '#/components/schemas/authorWithSeries' - 404: - $ref: '#/components/responses/author404' - /api/authors/{id}: - patch: - operationId: updateAuthorByID - summary: Update a single author by ID on server. This endpoint will merge two authors if the new author name matches another author in the database. - tags: - - Authors - parameters: - - $ref: '#/components/parameters/authorID' - - $ref: '#/components/parameters/asin' - - $ref: '#/components/parameters/authorName' - - $ref: '#/components/parameters/authorDescription' - - $ref: '#/components/parameters/authorImagePath' - responses: - 200: - description: updateAuthorByID OK - content: - application/json: - schema: - allOf: - - $ref: '#/components/schemas/author' - - $ref: '#/components/schemas/authorUpdated' - - type: object - properties: - merged: - description: Will only exist and be `true` if the author was merged with another author - type: boolean - nullable: true - 404: - $ref: '#/components/responses/author404' - /api/authors/{id}: - delete: - operationId: deleteAuthorByID - summary: Delete a single author by ID on server and remove author from all books. - tags: - - Authors - parameters: - - $ref: '#/components/parameters/authorID' - responses: - 200: - $ref: '#/components/responses/ok200' - 404: - $ref: '#/components/responses/author404' - /api/authors/{id}/image: - post: - operationId: setAuthorImageByID - summary: Set an author image using a provided URL. - tags: - - Authors - parameters: - - $ref: '#/components/parameters/authorID' - - $ref: '#/components/parameters/imageURL' - responses: - 200: - description: setAuthorImageByID OK - content: - application/json: - schema: - oneOf: - - $ref: '#/components/schemas/author' - 404: - $ref: '#/components/responses/author404' - /api/authors/{id}/image: - delete: - operationId: deleteAuthorImageByID - summary: Delete an author image from the server and remove the image from the database. - tags: - - Authors - parameters: - - $ref: '#/components/parameters/authorID' - responses: - 200: - $ref: '#/components/responses/ok200' - 404: - $ref: '#/components/responses/author404' - /api/authors/{id}/match: - post: - operationId: matchAuthorByID - summary: 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 - parameters: - - $ref: '#/components/parameters/authorID' - - $ref: '#/components/parameters/asin' - - $ref: '#/components/parameters/authorSearchName' - responses: - 200: - description: matchAuthorByID OK - content: - application/json: - schema: - allOf: - - $ref: '#/components/schemas/author' - - $ref: '#/components/schemas/authorUpdated' - 404: - $ref: '#/components/responses/author404' - /api/authors/{id}/image: - patch: - operationId: getAuthorImageByID - summary: Return the author image by author ID. - tags: - - Authors - parameters: - - $ref: '#/components/parameters/authorID' - - $ref: '#/components/parameters/imageWidth' - - $ref: '#/components/parameters/imageHeight' - - $ref: '#/components/parameters/imageFormat' - - $ref: '#/components/parameters/imageRaw' - responses: - 200: - description: getAuthorImageByID OK - content: - image/*: - schema: - type: string - format: binary - 404: - $ref: '#/components/responses/author404' +paths: + /api/authors/{id}: + get: + operationId: getAuthorByID + summary: Get a single author by ID on server + tags: + - Authors + parameters: + - $ref: './controllers/AuthorController.yaml#/components/parameters/authorID' + - $ref: './controllers/AuthorController.yaml#/components/parameters/authorInclude' + - $ref: './controllers/AuthorController.yaml#/components/parameters/authorLibraryId' + responses: + 200: + description: getAuthorByID OK + content: + application/json: + schema: + oneOf: + - $ref: './objects/entities/Author.yaml#/components/schemas/author' + - $ref: './objects/entities/Author.yaml#/components/schemas/authorWithItems' + - $ref: './objects/entities/Author.yaml#/components/schemas/authorWithSeries' + 404: + $ref: './controllers/AuthorController.yaml#/components/responses/author404' + patch: + operationId: updateAuthorByID + summary: Update a single author by ID on server. This endpoint will merge two authors if the new author name matches another author in the database. + tags: + - Authors + parameters: + - $ref: './controllers/AuthorController.yaml#/components/parameters/authorID' + - $ref: './controllers/AuthorController.yaml#/components/parameters/asin' + - $ref: './controllers/AuthorController.yaml#/components/parameters/authorName' + - $ref: './controllers/AuthorController.yaml#/components/parameters/authorDescription' + - $ref: './controllers/AuthorController.yaml#/components/parameters/authorImagePath' + responses: + 200: + description: updateAuthorByID OK + content: + application/json: + schema: + allOf: + - $ref: './objects/entities/Author.yaml#/components/schemas/author' + - $ref: './controllers/AuthorController.yaml#/components/schemas/authorUpdated' + - type: object + properties: + merged: + description: Will only exist and be `true` if the author was merged with another author + type: boolean + nullable: true + 404: + $ref: './controllers/AuthorController.yaml#/components/responses/author404' + delete: + operationId: deleteAuthorByID + summary: Delete a single author by ID on server and remove author from all books. + tags: + - Authors + parameters: + - $ref: './controllers/AuthorController.yaml#/components/parameters/authorID' + responses: + 200: + $ref: '#/components/responses/ok200' + 404: + $ref: './controllers/AuthorController.yaml#/components/responses/author404' + /api/authors/{id}/image: + post: + operationId: setAuthorImageByID + summary: Set an author image using a provided URL. + tags: + - Authors + parameters: + - $ref: './controllers/AuthorController.yaml#/components/parameters/authorID' + - $ref: './controllers/AuthorController.yaml#/components/parameters/imageURL' + responses: + 200: + description: setAuthorImageByID OK + content: + application/json: + schema: + oneOf: + - $ref: './objects/entities/Author.yaml#/components/schemas/author' + 404: + $ref: './controllers/AuthorController.yaml#/components/responses/author404' + delete: + operationId: deleteAuthorImageByID + summary: Delete an author image from the server and remove the image from the database. + tags: + - Authors + parameters: + - $ref: './controllers/AuthorController.yaml#/components/parameters/authorID' + responses: + 200: + $ref: '#/components/responses/ok200' + 404: + $ref: './controllers/AuthorController.yaml#/components/responses/author404' + patch: + operationId: getAuthorImageByID + summary: Return the author image by author ID. + tags: + - Authors + parameters: + - $ref: './controllers/AuthorController.yaml#/components/parameters/authorID' + - $ref: './controllers/AuthorController.yaml#/components/parameters/imageWidth' + - $ref: './controllers/AuthorController.yaml#/components/parameters/imageHeight' + - $ref: './controllers/AuthorController.yaml#/components/parameters/imageFormat' + - $ref: './controllers/AuthorController.yaml#/components/parameters/imageRaw' + responses: + 200: + description: getAuthorImageByID OK + content: + image/*: + schema: + type: string + format: binary + 404: + $ref: './controllers/AuthorController.yaml#/components/responses/author404' + /api/authors/{id}/match: + post: + operationId: matchAuthorByID + summary: 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 + parameters: + - $ref: './controllers/AuthorController.yaml#/components/parameters/authorID' + - $ref: './controllers/AuthorController.yaml#/components/parameters/asin' + - $ref: './controllers/AuthorController.yaml#/components/parameters/authorSearchName' + responses: + 200: + description: matchAuthorByID OK + content: + application/json: + schema: + allOf: + - $ref: './objects/entities/Author.yaml#/components/schemas/author' + - $ref: './controllers/AuthorController.yaml#/components/schemas/authorUpdated' + 404: + $ref: './controllers/AuthorController.yaml#/components/responses/author404' tags: - name: Authors description: Author endpoints From 7b856474afcf33cae2c0c9adccd1fa3fd1026593 Mon Sep 17 00:00:00 2001 From: Nicholas Wallace Date: Sun, 31 Mar 2024 22:48:58 +0000 Subject: [PATCH 03/39] Rename base document --- docs/{spec.yaml => root.yaml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{spec.yaml => root.yaml} (100%) diff --git a/docs/spec.yaml b/docs/root.yaml similarity index 100% rename from docs/spec.yaml rename to docs/root.yaml From 74dd24febf216edd9a9eda2f7778d943d39fbaf5 Mon Sep 17 00:00:00 2001 From: Nicholas Wallace Date: Mon, 1 Apr 2024 00:26:55 +0000 Subject: [PATCH 04/39] Bundled spec --- docs/openapi.json | 856 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 856 insertions(+) create mode 100644 docs/openapi.json diff --git a/docs/openapi.json b/docs/openapi.json new file mode 100644 index 00000000..8b47584b --- /dev/null +++ b/docs/openapi.json @@ -0,0 +1,856 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "Audiobookshelf API", + "version": "0.1.0", + "description": "Audiobookshelf API with autogenerated OpenAPI doc" + }, + "servers": [ + { + "url": "http://localhost:3000", + "description": "Development server" + } + ], + "components": { + "responses": { + "ok200": { + "description": "OK" + } + } + }, + "paths": { + "/api/authors/{id}": { + "get": { + "operationId": "getAuthorByID", + "summary": "Get a single author by ID on server", + "tags": [ + "Authors" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Author ID", + "required": true, + "schema": { + "type": "string", + "description": "The ID of the author.", + "format": "uuid", + "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" + } + }, + { + "name": "include", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "string", + "example": "items" + }, + "examples": { + "empty": { + "summary": "Do not return library items", + "value": "" + }, + "itemOnly": { + "summary": "Only return library items", + "value": "items" + }, + "itemsAndSeries": { + "summary": "Return library items and series", + "value": "items,series" + } + } + }, + { + "name": "library", + "in": "query", + "description": "The ID of the library to to include filter included items from.", + "required": false, + "schema": { + "type": "string", + "description": "The ID of the library.", + "format": "uuid", + "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" + } + } + ], + "responses": { + "200": { + "description": "getAuthorByID OK", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "description": "An author object which includes a description and image path.", + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The ID of the author.", + "format": "uuid", + "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" + }, + "asin": { + "type": "string", + "description": "The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.", + "nullable": true, + "example": "B000APZOQA" + }, + "name": { + "description": "The name of the author.", + "type": "string", + "example": "Terry Goodkind" + }, + "description": { + "description": "A description of the author. Will be null if there is none.", + "type": "string", + "nullable": true, + "example": "Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork,\n‘The Sword of Truth’. He has written 30+ major, bestselling novels, has been published in more than 20\nlanguages world-wide, and has sold more than 26 Million books. ‘The Sword of Truth’ is a revered literary\ntour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. Terry Goodkind's\nbrilliant books are character-driven stories, with a focus on the complexity of the human psyche. Goodkind\nhas an uncanny grasp for crafting compelling stories about people like you and me, trapped in terrifying\nsituations.\n" + }, + "imagePath": { + "description": "The absolute path for the author image located in the `metadata/` directory. Will be null if there is no image.", + "type": "string", + "nullable": true, + "example": "/metadata/authors/aut_bxxbyjiptmgb56yzoz.jpg" + }, + "addedAt": { + "type": "integer", + "description": "The time (in ms since POSIX epoch) when added to the server.", + "example": 1633522963509 + }, + "updatedAt": { + "type": "integer", + "description": "The time (in ms since POSIX epoch) when last updated.", + "example": 1633522963509 + } + } + }, + { + "type": "object", + "description": "The author schema with an array of items they are associated with.", + "allOf": [ + { + "description": "An author object which includes a description and image path.", + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The ID of the author.", + "format": "uuid", + "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" + }, + "asin": { + "type": "string", + "description": "The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.", + "nullable": true, + "example": "B000APZOQA" + }, + "name": { + "description": "The name of the author.", + "type": "string", + "example": "Terry Goodkind" + }, + "description": { + "description": "A description of the author. Will be null if there is none.", + "type": "string", + "nullable": true, + "example": "Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork,\n‘The Sword of Truth’. He has written 30+ major, bestselling novels, has been published in more than 20\nlanguages world-wide, and has sold more than 26 Million books. ‘The Sword of Truth’ is a revered literary\ntour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. Terry Goodkind's\nbrilliant books are character-driven stories, with a focus on the complexity of the human psyche. Goodkind\nhas an uncanny grasp for crafting compelling stories about people like you and me, trapped in terrifying\nsituations.\n" + }, + "imagePath": { + "description": "The absolute path for the author image located in the `metadata/` directory. Will be null if there is no image.", + "type": "string", + "nullable": true, + "example": "/metadata/authors/aut_bxxbyjiptmgb56yzoz.jpg" + }, + "addedAt": { + "type": "integer", + "description": "The time (in ms since POSIX epoch) when added to the server.", + "example": 1633522963509 + }, + "updatedAt": { + "type": "integer", + "description": "The time (in ms since POSIX epoch) when last updated.", + "example": 1633522963509 + } + } + }, + { + "type": "object", + "properties": { + "libraryItems": { + "description": "The items associated with the author", + "type": "string" + } + } + } + ] + }, + { + "type": "object", + "description": "The author schema with an array of items and series they are associated with.", + "allOf": [ + { + "type": "object", + "description": "The author schema with an array of items they are associated with.", + "allOf": [ + { + "description": "An author object which includes a description and image path.", + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The ID of the author.", + "format": "uuid", + "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" + }, + "asin": { + "type": "string", + "description": "The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.", + "nullable": true, + "example": "B000APZOQA" + }, + "name": { + "description": "The name of the author.", + "type": "string", + "example": "Terry Goodkind" + }, + "description": { + "description": "A description of the author. Will be null if there is none.", + "type": "string", + "nullable": true, + "example": "Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork,\n‘The Sword of Truth’. He has written 30+ major, bestselling novels, has been published in more than 20\nlanguages world-wide, and has sold more than 26 Million books. ‘The Sword of Truth’ is a revered literary\ntour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. Terry Goodkind's\nbrilliant books are character-driven stories, with a focus on the complexity of the human psyche. Goodkind\nhas an uncanny grasp for crafting compelling stories about people like you and me, trapped in terrifying\nsituations.\n" + }, + "imagePath": { + "description": "The absolute path for the author image located in the `metadata/` directory. Will be null if there is no image.", + "type": "string", + "nullable": true, + "example": "/metadata/authors/aut_bxxbyjiptmgb56yzoz.jpg" + }, + "addedAt": { + "type": "integer", + "description": "The time (in ms since POSIX epoch) when added to the server.", + "example": 1633522963509 + }, + "updatedAt": { + "type": "integer", + "description": "The time (in ms since POSIX epoch) when last updated.", + "example": 1633522963509 + } + } + }, + { + "type": "object", + "properties": { + "libraryItems": { + "description": "The items associated with the author", + "type": "string" + } + } + } + ] + }, + { + "type": "object", + "properties": { + "series": { + "description": "The series associated with the author", + "type": "array", + "items": { + "type": "object", + "description": "Series and the included library items that an author has written.", + "properties": { + "id": { + "type": "string", + "description": "The ID of the series.", + "format": "uuid", + "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" + }, + "name": { + "description": "The name of the series.", + "type": "string", + "example": "Sword of Truth" + }, + "items": { + "description": "The items in the series. Each library item's media's metadata will have a `series` attribute, a `Series Sequence`, which is the matching series.", + "type": "array", + "items": {} + } + } + } + } + } + } + ] + } + ] + } + } + } + }, + "404": { + "description": "Author not found.", + "content": { + "text/html": { + "schema": { + "type": "string", + "example": "Not found" + } + } + } + } + } + }, + "patch": { + "operationId": "updateAuthorByID", + "summary": "Update a single author by ID on server. This endpoint will merge two authors if the new author name matches another author in the database.", + "tags": [ + "Authors" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Author ID", + "required": true, + "schema": { + "type": "string", + "description": "The ID of the author.", + "format": "uuid", + "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" + } + }, + { + "name": "asin", + "in": "query", + "description": "The Audible Identifier (ASIN).", + "required": false, + "schema": { + "type": "string", + "description": "The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.", + "nullable": true, + "example": "B000APZOQA" + } + }, + { + "name": "name", + "in": "query", + "description": "The new name of the author.", + "required": false, + "schema": { + "description": "The name of the author.", + "type": "string", + "example": "Terry Goodkind" + } + }, + { + "name": "description", + "in": "query", + "description": "The new description of the author.", + "required": false, + "schema": { + "type": "string", + "nullable": true, + "example": "Terry Goodkind is a" + } + }, + { + "name": "imagePath", + "in": "query", + "description": "The new absolute path for the author image.", + "required": false, + "schema": { + "type": "string", + "nullable": true, + "example": "/metadata/authors/aut_z3leimgybl7uf3y4ab.jpg" + } + } + ], + "responses": { + "200": { + "description": "updateAuthorByID OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "description": "An author object which includes a description and image path.", + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The ID of the author.", + "format": "uuid", + "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" + }, + "asin": { + "type": "string", + "description": "The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.", + "nullable": true, + "example": "B000APZOQA" + }, + "name": { + "description": "The name of the author.", + "type": "string", + "example": "Terry Goodkind" + }, + "description": { + "description": "A description of the author. Will be null if there is none.", + "type": "string", + "nullable": true, + "example": "Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork,\n‘The Sword of Truth’. He has written 30+ major, bestselling novels, has been published in more than 20\nlanguages world-wide, and has sold more than 26 Million books. ‘The Sword of Truth’ is a revered literary\ntour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. Terry Goodkind's\nbrilliant books are character-driven stories, with a focus on the complexity of the human psyche. Goodkind\nhas an uncanny grasp for crafting compelling stories about people like you and me, trapped in terrifying\nsituations.\n" + }, + "imagePath": { + "description": "The absolute path for the author image located in the `metadata/` directory. Will be null if there is no image.", + "type": "string", + "nullable": true, + "example": "/metadata/authors/aut_bxxbyjiptmgb56yzoz.jpg" + }, + "addedAt": { + "type": "integer", + "description": "The time (in ms since POSIX epoch) when added to the server.", + "example": 1633522963509 + }, + "updatedAt": { + "type": "integer", + "description": "The time (in ms since POSIX epoch) when last updated.", + "example": 1633522963509 + } + } + }, + { + "description": "Whether the author was updated without errors. Will not exist if author was merged.", + "type": "boolean", + "nullable": true + }, + { + "type": "object", + "properties": { + "merged": { + "description": "Will only exist and be `true` if the author was merged with another author", + "type": "boolean", + "nullable": true + } + } + } + ] + } + } + } + }, + "404": { + "description": "Author not found.", + "content": { + "text/html": { + "schema": { + "type": "string", + "example": "Not found" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteAuthorByID", + "summary": "Delete a single author by ID on server and remove author from all books.", + "tags": [ + "Authors" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Author ID", + "required": true, + "schema": { + "type": "string", + "description": "The ID of the author.", + "format": "uuid", + "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ok200" + }, + "404": { + "description": "Author not found.", + "content": { + "text/html": { + "schema": { + "type": "string", + "example": "Not found" + } + } + } + } + } + } + }, + "/api/authors/{id}/image": { + "post": { + "operationId": "setAuthorImageByID", + "summary": "Set an author image using a provided URL.", + "tags": [ + "Authors" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Author ID", + "required": true, + "schema": { + "type": "string", + "description": "The ID of the author.", + "format": "uuid", + "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" + } + }, + { + "name": "url", + "in": "query", + "description": "The URL of the image to add to the server", + "required": true, + "schema": { + "type": "string", + "format": "uri", + "example": "https://images-na.ssl-images-amazon.com/images/I/51NoQTm33OL.__01_SX120_CR0,0,120,120__.jpg" + } + } + ], + "responses": { + "200": { + "description": "setAuthorImageByID OK", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "description": "An author object which includes a description and image path.", + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The ID of the author.", + "format": "uuid", + "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" + }, + "asin": { + "type": "string", + "description": "The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.", + "nullable": true, + "example": "B000APZOQA" + }, + "name": { + "description": "The name of the author.", + "type": "string", + "example": "Terry Goodkind" + }, + "description": { + "description": "A description of the author. Will be null if there is none.", + "type": "string", + "nullable": true, + "example": "Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork,\n‘The Sword of Truth’. He has written 30+ major, bestselling novels, has been published in more than 20\nlanguages world-wide, and has sold more than 26 Million books. ‘The Sword of Truth’ is a revered literary\ntour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. Terry Goodkind's\nbrilliant books are character-driven stories, with a focus on the complexity of the human psyche. Goodkind\nhas an uncanny grasp for crafting compelling stories about people like you and me, trapped in terrifying\nsituations.\n" + }, + "imagePath": { + "description": "The absolute path for the author image located in the `metadata/` directory. Will be null if there is no image.", + "type": "string", + "nullable": true, + "example": "/metadata/authors/aut_bxxbyjiptmgb56yzoz.jpg" + }, + "addedAt": { + "type": "integer", + "description": "The time (in ms since POSIX epoch) when added to the server.", + "example": 1633522963509 + }, + "updatedAt": { + "type": "integer", + "description": "The time (in ms since POSIX epoch) when last updated.", + "example": 1633522963509 + } + } + } + ] + } + } + } + }, + "404": { + "description": "Author not found.", + "content": { + "text/html": { + "schema": { + "type": "string", + "example": "Not found" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteAuthorImageByID", + "summary": "Delete an author image from the server and remove the image from the database.", + "tags": [ + "Authors" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Author ID", + "required": true, + "schema": { + "type": "string", + "description": "The ID of the author.", + "format": "uuid", + "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ok200" + }, + "404": { + "description": "Author not found.", + "content": { + "text/html": { + "schema": { + "type": "string", + "example": "Not found" + } + } + } + } + } + }, + "patch": { + "operationId": "getAuthorImageByID", + "summary": "Return the author image by author ID.", + "tags": [ + "Authors" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Author ID", + "required": true, + "schema": { + "type": "string", + "description": "The ID of the author.", + "format": "uuid", + "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" + } + }, + { + "name": "width", + "in": "query", + "description": "The requested width of image in pixels.", + "schema": { + "type": "integer", + "default": 400, + "example": 400 + }, + "example": 400 + }, + { + "name": "height", + "in": "query", + "description": "The requested height of image in pixels. If `null`, the height is scaled to maintain aspect ratio based on the requested width.", + "schema": { + "type": "integer", + "nullable": true, + "default": null, + "example": 600 + }, + "examples": { + "scaleHeight": { + "summary": "Scale height with width", + "value": null + }, + "fixedHeight": { + "summary": "Force height of image", + "value": 600 + } + } + }, + { + "name": "format", + "in": "query", + "description": "The requested output format.", + "schema": { + "type": "string", + "default": "jpeg", + "example": "webp" + } + }, + { + "name": "raw", + "in": "query", + "description": "Return the raw image without scaling if true.", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "getAuthorImageByID OK", + "content": { + "image/*": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "404": { + "description": "Author not found.", + "content": { + "text/html": { + "schema": { + "type": "string", + "example": "Not found" + } + } + } + } + } + } + }, + "/api/authors/{id}/match": { + "post": { + "operationId": "matchAuthorByID", + "summary": "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" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Author ID", + "required": true, + "schema": { + "type": "string", + "description": "The ID of the author.", + "format": "uuid", + "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" + } + }, + { + "name": "asin", + "in": "query", + "description": "The Audible Identifier (ASIN).", + "required": false, + "schema": { + "type": "string", + "description": "The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.", + "nullable": true, + "example": "B000APZOQA" + } + }, + { + "name": "q", + "in": "query", + "description": "The name of the author to use for searching.", + "required": false, + "schema": { + "type": "string", + "example": "Terry Goodkind" + } + } + ], + "responses": { + "200": { + "description": "matchAuthorByID OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "description": "An author object which includes a description and image path.", + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The ID of the author.", + "format": "uuid", + "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" + }, + "asin": { + "type": "string", + "description": "The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.", + "nullable": true, + "example": "B000APZOQA" + }, + "name": { + "description": "The name of the author.", + "type": "string", + "example": "Terry Goodkind" + }, + "description": { + "description": "A description of the author. Will be null if there is none.", + "type": "string", + "nullable": true, + "example": "Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork,\n‘The Sword of Truth’. He has written 30+ major, bestselling novels, has been published in more than 20\nlanguages world-wide, and has sold more than 26 Million books. ‘The Sword of Truth’ is a revered literary\ntour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. Terry Goodkind's\nbrilliant books are character-driven stories, with a focus on the complexity of the human psyche. Goodkind\nhas an uncanny grasp for crafting compelling stories about people like you and me, trapped in terrifying\nsituations.\n" + }, + "imagePath": { + "description": "The absolute path for the author image located in the `metadata/` directory. Will be null if there is no image.", + "type": "string", + "nullable": true, + "example": "/metadata/authors/aut_bxxbyjiptmgb56yzoz.jpg" + }, + "addedAt": { + "type": "integer", + "description": "The time (in ms since POSIX epoch) when added to the server.", + "example": 1633522963509 + }, + "updatedAt": { + "type": "integer", + "description": "The time (in ms since POSIX epoch) when last updated.", + "example": 1633522963509 + } + } + }, + { + "description": "Whether the author was updated without errors. Will not exist if author was merged.", + "type": "boolean", + "nullable": true + } + ] + } + } + } + }, + "404": { + "description": "Author not found.", + "content": { + "text/html": { + "schema": { + "type": "string", + "example": "Not found" + } + } + } + } + } + } + } + }, + "tags": [ + { + "name": "Authors", + "description": "Author endpoints" + } + ] +} From ca7eaf97502676f0933925ad9450396f0c18161f Mon Sep 17 00:00:00 2001 From: Nicholas Wallace Date: Mon, 1 Apr 2024 00:44:51 +0000 Subject: [PATCH 05/39] OpenAPI spec readme --- docs/README.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..c6f278ed --- /dev/null +++ b/docs/README.md @@ -0,0 +1,30 @@ +# OpenAPI specification + +This directory includes the OpenAPI spec for the ABS server. +The spec is made up of a number of individual `yaml` files located here and in the subfolders, with `root.yaml` being the file that references all of the others. +The files are organized to have the same hierarchy as the server source files. +The full spec is bundled into one file in `openapi.json`. + +The spec is linted and bundled by the [`vacuum` tool](https://quobix.com/vacuum/). +The spec can also be tested with a real server using the [`wiretap` tool](https://pb33f.io/wiretap/). +Both of these tools are created by [pb33f](https://pb33f.io/). + +### Bundling the spec +The command to bundle the spec into a `yaml` file is `vacuum bundle root.yaml openapi.yaml`. + +The current version of `vacuum` cannot convert input `yaml` files to `json` files. +To convert the spec to `json`, you can use the `yq` tool or another tool. + +The command to convert the spec using `yq` is `yq -p yaml -o json openapi.yaml > openapi.json`. + +### Viewing report +To generate an HTML report, you can use `vacuum html-report [file]` to generate `report.html` and view the report in your browser. + +### Putting it all together +The full command that I run to bundle the spec and generate the report is: + +``` +vacuum bundle root.yaml openapi.yaml && \ +yq -p yaml -o json openapi.yaml > openapi.json && \ +vacuum html-report openapi.json +``` From c8957fe373e97f33e08fe778a09b99811cf13e2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rasmus=20Kr=C3=A4mer?= Date: Mon, 1 Apr 2024 16:20:09 +0200 Subject: [PATCH 06/39] Add client name to possible device info lines --- client/pages/config/sessions.vue | 1 + 1 file changed, 1 insertion(+) diff --git a/client/pages/config/sessions.vue b/client/pages/config/sessions.vue index 162c7747..0437cfd2 100644 --- a/client/pages/config/sessions.vue +++ b/client/pages/config/sessions.vue @@ -396,6 +396,7 @@ export default { var lines = [] if (deviceInfo.osName) lines.push(`${deviceInfo.osName} ${deviceInfo.osVersion}`) if (deviceInfo.browserName) lines.push(deviceInfo.browserName) + if (deviceInfo.clientName) lines.push(`${deviceInfo.clientName} ${deviceInfo.clientVersion}`) if (deviceInfo.manufacturer && deviceInfo.model) lines.push(`${deviceInfo.manufacturer} ${deviceInfo.model}`) if (deviceInfo.sdkVersion) lines.push(`SDK Version: ${deviceInfo.sdkVersion}`) From 116a7fb994e156755053c43a8be1d7356bf3e786 Mon Sep 17 00:00:00 2001 From: SunX Date: Wed, 3 Apr 2024 09:55:33 +0800 Subject: [PATCH 07/39] Update zh-cn.json --- client/strings/zh-cn.json | 60 +++++++++++++++++++-------------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/client/strings/zh-cn.json b/client/strings/zh-cn.json index 69b03fb3..4ff8d74b 100644 --- a/client/strings/zh-cn.json +++ b/client/strings/zh-cn.json @@ -32,8 +32,8 @@ "ButtonHide": "隐藏", "ButtonHome": "首页", "ButtonIssues": "问题", - "ButtonJumpBackward": "Jump Backward", - "ButtonJumpForward": "Jump Forward", + "ButtonJumpBackward": "向后跳转", + "ButtonJumpForward": "向前跳转", "ButtonLatest": "最新", "ButtonLibrary": "媒体库", "ButtonLogout": "注销", @@ -43,8 +43,8 @@ "ButtonMatchAllAuthors": "匹配所有作者", "ButtonMatchBooks": "匹配图书", "ButtonNevermind": "没有关系", - "ButtonNext": "Next", - "ButtonNextChapter": "Next Chapter", + "ButtonNext": "下一个", + "ButtonNextChapter": "下一章节", "ButtonOk": "确定", "ButtonOpenFeed": "打开源", "ButtonOpenManager": "打开管理器", @@ -52,8 +52,8 @@ "ButtonPlay": "播放", "ButtonPlaying": "正在播放", "ButtonPlaylists": "播放列表", - "ButtonPrevious": "Previous", - "ButtonPreviousChapter": "Previous Chapter", + "ButtonPrevious": "上一个", + "ButtonPreviousChapter": "上一章节", "ButtonPurgeAllCache": "清理所有缓存", "ButtonPurgeItemsCache": "清理项目缓存", "ButtonPurgeMediaProgress": "清理媒体进度", @@ -61,7 +61,7 @@ "ButtonQueueRemoveItem": "从队列中移除", "ButtonQuickMatch": "快速匹配", "ButtonRead": "读取", - "ButtonRefresh": "Refresh", + "ButtonRefresh": "刷新", "ButtonRemove": "移除", "ButtonRemoveAll": "移除所有", "ButtonRemoveAllLibraryItems": "移除所有媒体库项目", @@ -113,7 +113,7 @@ "HeaderCollectionItems": "收藏项目", "HeaderCover": "封面", "HeaderCurrentDownloads": "当前下载", - "HeaderCustomMetadataProviders": "Custom Metadata Providers", + "HeaderCustomMetadataProviders": "自定义元数据提供者", "HeaderDetails": "详情", "HeaderDownloadQueue": "下载队列", "HeaderEbookFiles": "电子书文件", @@ -184,7 +184,7 @@ "HeaderUpdateDetails": "更新详情", "HeaderUpdateLibrary": "更新媒体库", "HeaderUsers": "用户", - "HeaderYearReview": "Year {0} in Review", + "HeaderYearReview": "{0} 年回顾", "HeaderYourStats": "你的统计数据", "LabelAbridged": "概要", "LabelAccountType": "帐户类型", @@ -294,9 +294,9 @@ "LabelFolders": "文件夹", "LabelFontBold": "Bold", "LabelFontFamily": "字体系列", - "LabelFontItalic": "Italic", + "LabelFontItalic": "斜体", "LabelFontScale": "字体比例", - "LabelFontStrikethrough": "Strikethrough", + "LabelFontStrikethrough": "删除线", "LabelFormat": "编码格式", "LabelGenre": "流派", "LabelGenres": "流派", @@ -355,8 +355,8 @@ "LabelMetaTags": "元标签", "LabelMinute": "分钟", "LabelMissing": "丢失", - "LabelMissingEbook": "Has no ebook", - "LabelMissingSupplementaryEbook": "Has no supplementary ebook", + "LabelMissingEbook": "没有电子书", + "LabelMissingSupplementaryEbook": "没有补充电子书", "LabelMobileRedirectURIs": "允许移动应用重定向 URI", "LabelMobileRedirectURIsDescription": "这是移动应用程序的有效重定向 URI 白名单. 默认值为 audiobookshelf://oauth，您可以删除它或添加其他 URI 以进行第三方应用集成. 使用星号 (*) 作为唯一条目允许任何 URI.", "LabelMore": "更多", @@ -385,9 +385,9 @@ "LabelNotStarted": "未开始", "LabelNumberOfBooks": "图书数量", "LabelNumberOfEpisodes": "# 集", - "LabelOpenIDAdvancedPermsClaimDescription": "Name of the OpenID claim that contains advanced permissions for user actions within the application which will apply to non-admin roles (if configured). If the claim is missing from the response, access to ABS will be denied. If a single option is missing, it will be treated as false. Ensure the identity provider's claim matches the expected structure:", - "LabelOpenIDClaims": "Leave the following options empty to disable advanced group and permissions assignment, automatically assigning 'User' group then.", - "LabelOpenIDGroupClaimDescription": "Name of the OpenID claim that contains a list of the user's groups. Commonly referred to as groups. If configured, the application will automatically assign roles based on the user's group memberships, provided that these groups are named case-insensitively 'admin', 'user', or 'guest' in the claim. The claim should contain a list, and if a user belongs to multiple groups, the application will assign the role corresponding to the highest level of access. If no group matches, access will be denied.", + "LabelOpenIDAdvancedPermsClaimDescription": "OpenID 声明的名称, 该声明包含应用程序内用户操作的高级权限, 该权限将应用于非管理员角色(如果已配置). 如果响应中缺少声明, 获取 ABS 的权限将被拒绝. 如果缺少单个选项, 它将被视为 禁用. 确保身份提供者的声明与预期结构匹配:", + "LabelOpenIDClaims": "将以下选项留空以禁用高级组和权限分配, 然后自动分配 'User' 组.", + "LabelOpenIDGroupClaimDescription": "OpenID 声明的名称, 该声明包含用户组的列表. 通常称为组如果已配置, 应用程序将根据用户的组成员身份自动分配角色, 前提是这些组在声明中以不区分大小写的方式命名为 'Admin', 'User' 或 'Guest'. 声明应包含一个列表, 如果用户属于多个组, 则应用程序将分配与最高访问级别相对应的角色. 如果没有组匹配, 访问将被拒绝.", "LabelOpenRSSFeed": "打开 RSS 源", "LabelOverwrite": "覆盖", "LabelPassword": "密码", @@ -399,7 +399,7 @@ "LabelPermissionsDownload": "可以下载", "LabelPermissionsUpdate": "可以更新", "LabelPermissionsUpload": "可以上传", - "LabelPersonalYearReview": "Your Year in Review ({0})", + "LabelPersonalYearReview": "你的年度回顾 ({0})", "LabelPhotoPathURL": "图片路径或 URL", "LabelPlaylists": "播放列表", "LabelPlayMethod": "播放方法", @@ -426,7 +426,7 @@ "LabelRegion": "区域", "LabelReleaseDate": "发布日期", "LabelRemoveCover": "移除封面", - "LabelRowsPerPage": "Rows per page", + "LabelRowsPerPage": "每页行数", "LabelRSSFeedCustomOwnerEmail": "自定义所有者电子邮件", "LabelRSSFeedCustomOwnerName": "自定义所有者名称", "LabelRSSFeedOpen": "打开 RSS 源", @@ -439,13 +439,13 @@ "LabelSeason": "季", "LabelSelectAllEpisodes": "选择所有剧集", "LabelSelectEpisodesShowing": "选择正在播放的 {0} 剧集", - "LabelSelectUsers": "Select users", + "LabelSelectUsers": "选择用户", "LabelSendEbookToDevice": "发送电子书到...", "LabelSequence": "序列", "LabelSeries": "系列", "LabelSeriesName": "系列名称", "LabelSeriesProgress": "系列进度", - "LabelServerYearReview": "Server Year in Review ({0})", + "LabelServerYearReview": "服务器年度回顾 ({0})", "LabelSetEbookAsPrimary": "设置为主", "LabelSetEbookAsSupplementary": "设置为补充", "LabelSettingsAudiobooksOnly": "只有有声读物", @@ -467,8 +467,8 @@ "LabelSettingsHideSingleBookSeriesHelp": "只有一本书的系列将从系列页面和主页书架中隐藏.", "LabelSettingsHomePageBookshelfView": "首页使用书架视图", "LabelSettingsLibraryBookshelfView": "媒体库使用书架视图", - "LabelSettingsOnlyShowLaterBooksInContinueSeries": "Skip earlier books in Continue Series", - "LabelSettingsOnlyShowLaterBooksInContinueSeriesHelp": "The Continue Series home page shelf shows the first book not started in series that have at least one book finished and no books in progress. Enabling this setting will continue series from the furthest completed book instead of the first book not started.", + "LabelSettingsOnlyShowLaterBooksInContinueSeries": "跳过继续系列中的早期书籍", + "LabelSettingsOnlyShowLaterBooksInContinueSeriesHelp": "继续系列主页书架显示系列中未开始的第一本书, 该系列至少有一本书已完成且没有正在进行的书. 启用此设置将从最远完成的书开始系列, 而不是从第一本书开始.", "LabelSettingsParseSubtitles": "解析副标题", "LabelSettingsParseSubtitlesHelp": "从有声读物文件夹中提取副标题.
副标题必须用 \" - \" 分隔.
例: \"书名 - 这里是副标题\" 则显示副标题 \"这里是副标题\"", "LabelSettingsPreferMatchedMetadata": "首选匹配的元数据", @@ -514,10 +514,10 @@ "LabelTagsAccessibleToUser": "用户可访问的标签", "LabelTagsNotAccessibleToUser": "用户无法访问标签", "LabelTasks": "正在运行的任务", - "LabelTextEditorBulletedList": "Bulleted list", - "LabelTextEditorLink": "Link", - "LabelTextEditorNumberedList": "Numbered list", - "LabelTextEditorUnlink": "Unlink", + "LabelTextEditorBulletedList": "项目符号列表", + "LabelTextEditorLink": "链接", + "LabelTextEditorNumberedList": "编号列表", + "LabelTextEditorUnlink": "取消链接", "LabelTheme": "主题", "LabelThemeDark": "黑暗", "LabelThemeLight": "明亮", @@ -564,8 +564,8 @@ "LabelViewQueue": "查看播放列表", "LabelVolume": "音量", "LabelWeekdaysToRun": "工作日运行", - "LabelYearReviewHide": "Hide Year in Review", - "LabelYearReviewShow": "See Year in Review", + "LabelYearReviewHide": "隐藏年度回顾", + "LabelYearReviewShow": "查看年度回顾", "LabelYourAudiobookDuration": "你的有声读物持续时间", "LabelYourBookmarks": "你的书签", "LabelYourPlaylists": "你的播放列表", @@ -602,7 +602,7 @@ "MessageConfirmRemoveCollection": "你确定要移除收藏 \"{0}\"?", "MessageConfirmRemoveEpisode": "你确定要移除剧集 \"{0}\"?", "MessageConfirmRemoveEpisodes": "你确定要移除 {0} 剧集?", - "MessageConfirmRemoveListeningSessions": "Are you sure you want to remove {0} listening sessions?", + "MessageConfirmRemoveListeningSessions": "你确定要移除 {0} 收听会话吗?", "MessageConfirmRemoveNarrator": "你确定要删除演播者 \"{0}\"?", "MessageConfirmRemovePlaylist": "你确定要移除播放列表 \"{0}\"?", "MessageConfirmRenameGenre": "你确定要将所有项目流派 \"{0}\" 重命名到 \"{1}\"?", @@ -779,4 +779,4 @@ "ToastSocketFailedToConnect": "网络连接失败", "ToastUserDeleteFailed": "删除用户失败", "ToastUserDeleteSuccess": "用户已删除" -} \ No newline at end of file +} From c5785e9c200c10259944c926b17923460d28917b Mon Sep 17 00:00:00 2001 From: advplyr Date: Wed, 3 Apr 2024 18:41:41 -0500 Subject: [PATCH 08/39] Update:Increase breakpoint for player to change buttons to two lines #2799 --- client/components/app/MediaPlayerContainer.vue | 8 ++++---- client/components/player/PlayerPlaybackControls.vue | 8 ++++---- client/components/player/PlayerUi.vue | 2 +- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/client/components/app/MediaPlayerContainer.vue b/client/components/app/MediaPlayerContainer.vue index 120231dc..081cd708 100644 --- a/client/components/app/MediaPlayerContainer.vue +++ b/client/components/app/MediaPlayerContainer.vue @@ -1,10 +1,10 @@