diff --git a/docs/controllers/AuthorController.yaml b/docs/controllers/AuthorController.yaml index feeed93b7..9a067c5fa 100644 --- a/docs/controllers/AuthorController.yaml +++ b/docs/controllers/AuthorController.yaml @@ -8,115 +8,43 @@ components: description: Whether the author was merged with another author. Will not exist if author was updated. type: boolean nullable: true - requestBody: - asin: - name: asin - in: requestBody - description: The Audible Identifier (ASIN). - schema: - $ref: '../objects/entities/Author.yaml#/components/schemas/authorAsin' - authorDescription: - name: description - in: requestBody - description: The new description of the author. - 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. authorInclude: - name: include - in: requestBody - 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. - 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' + description: A comma separated list of what to include with the author. The options are `items` and `series`. `series` will only have an effect if `items` is included. For example, the value `items,series` will include both library items and series. + type: string + example: 'items' authorLibraryId: - name: library - in: requestBody - description: The ID of the library to to include filter included items from. - schema: - $ref: '../objects/Library.yaml#/components/schemas/libraryId' + $ref: '../objects/Library.yaml#/components/schemas/libraryId' authorSearchName: - name: q - in: requestBody description: The name of the author to use for searching. - schema: - type: string - example: Terry Goodkind + type: string + example: Terry Goodkind authorName: - name: name - in: requestBody - description: The new name of the author. - schema: - $ref: '../objects/entities/Author.yaml#/components/schemas/authorName' - authorImagePath: - name: imagePath - in: requestBody - description: The new absolute path for the author image. - required: false - schema: - type: string - nullable: true - example: /metadata/authors/aut_z3leimgybl7uf3y4ab.jpg + $ref: '../objects/entities/Author.yaml#/components/schemas/authorName' imageUrl: - name: url - in: requestBody 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 + 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: requestBody description: The requested width of image in pixels. - schema: - type: integer - default: 400 - example: 400 + type: integer + default: 400 example: 400 imageHeight: - name: height - in: requestBody 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 + type: integer + nullable: true + default: null + example: 600 imageFormat: - name: format - in: requestBody description: The requested output format. - schema: - type: string - default: jpeg - example: webp + type: string + default: jpeg + example: webp imageRaw: - name: raw - in: requestBody description: Return the raw image without scaling if true. - schema: - type: boolean - default: false + type: boolean + default: false responses: author200: description: Author found. @@ -154,9 +82,9 @@ paths: schema: properties: include: - $ref: '#/components/requestBody/authorInclude' + $ref: '#/components/schemas/authorInclude' library: - $ref: '#/components/requestBody/authorLibraryId' + $ref: '#/components/schemas/authorLibraryId' responses: '200': description: getAuthorById OK @@ -173,20 +101,19 @@ paths: tags: - Authors requestBody: - required: true description: The author object to update. content: application/json: schema: properties: name: - $ref: '#/components/requestBody/authorName' + $ref: '#/components/schemas/authorName' description: - $ref: '#/components/requestBody/authorDescription' + $ref: '../objects/entities/Author.yaml#/components/schemas/authorDescription' imagePath: - $ref: '#/components/requestBody/authorImagePath' + $ref: '../objects/entities/Author.yaml#/components/schemas/authorImagePath' asin: - $ref: '#/components/requestBody/asin' + $ref: '../objects/entities/Author.yaml#/components/schemas/authorAsin' responses: '200': description: updateAuthorById OK @@ -237,13 +164,13 @@ paths: schema: properties: width: - $ref: '#/components/requestBody/imageWidth' + $ref: '#/components/schemas/imageWidth' height: - $ref: '#/components/requestBody/imageHeight' + $ref: '#/components/schemas/imageHeight' format: - $ref: '#/components/requestBody/imageFormat' + $ref: '#/components/schemas/imageFormat' raw: - $ref: '#/components/requestBody/imageRaw' + $ref: '#/components/schemas/imageRaw' responses: '200': description: getAuthorImageById OK @@ -268,15 +195,13 @@ paths: description: Add an author image to the server. The image will be downloaded from the provided URL and stored on the server. tags: - Authors - requestBody: - $ref: '#/components/requestBody/imageUrl' requestBody: required: true description: The author image to add by URL. content: application/json: schema: - $ref: '#/components/requestBody/imageUrl' + $ref: '#/components/schemas/imageUrl' responses: '200': description: addAuthorImageById OK @@ -294,20 +219,19 @@ paths: tags: - Authors requestBody: - required: true description: The author image to update. content: application/json: schema: properties: width: - $ref: '#/components/requestBody/imageWidth' + $ref: '#/components/schemas/imageWidth' height: - $ref: '#/components/requestBody/imageHeight' + $ref: '#/components/schemas/imageHeight' format: - $ref: '#/components/requestBody/imageFormat' + $ref: '#/components/schemas/imageFormat' raw: - $ref: '#/components/requestBody/imageRaw' + $ref: '#/components/schemas/imageRaw' responses: '200': description: updateAuthorImageById OK @@ -350,10 +274,8 @@ paths: application/json: schema: oneOf: - asin: - $ref: '#/components/requestBody/asin' - q: - $ref: '#/components/requestBody/authorSearchName' + - $ref: '../objects/entities/Author.yaml#/components/schemas/authorAsin' + - $ref: '#/components/schemas/authorSearchName' responses: '200': description: matchAuthorById OK diff --git a/docs/controllers/LibraryController.yaml b/docs/controllers/LibraryController.yaml index f69f00116..5967b9928 100644 --- a/docs/controllers/LibraryController.yaml +++ b/docs/controllers/LibraryController.yaml @@ -17,101 +17,47 @@ components: type: boolean description: Whether collapse series was set in the request. example: true - libraryInclude: - type: string - description: The fields from the response. - example: 'rssfeed' - requestBody: - libraryName: - name: name - in: requestBody - description: The name of the library. - content: - application/json: - schema: - type: string - example: My Audiobooks libraryFolders: - name: folders - in: requestBody - summary: The folders of the library. description: The folders of the library. Only specify the fullPath. - content: - application/json: - schema: - type: array - items: - $ref: '../objects/Folder.yaml#/components/schemas/folder' + type: array + items: + $ref: '../objects/Folder.yaml#/components/schemas/folder' libraryDisplayOrder: - name: displayOrder - in: requestBody description: The display order of the library. Must be >= 1. - schema: - type: integer - minimum: 1 - example: 1 + type: integer + minimum: 1 + example: 1 libraryIcon: - name: icon - in: requestBody - summary: The icon of library. description: The icon of the library. See Library Icons for a list of possible icons. - schema: - type: string - example: 'audiobookshelf' + type: string + example: 'audiobookshelf' libraryMediaType: - name: mediaType - in: requestBody - summary: The type of media the library contains. description: The type of media that the library contains. Must be `book` or `podcast`. - schema: - type: string - example: 'book' + type: string + example: 'book' libraryProvider: - name: provider - in: requestBody - summary: Preferred metadata provider for the library. description: Preferred metadata provider for the library. See Metadata Providers for a list of possible providers. - schema: - type: string - example: 'audible' + type: string + example: 'audible' librarySettings: - name: settings - in: requestBody - summary: The settings for the library. - description: The settings for the library. - schema: - $ref: '../objects/Library.yaml#/components/schemas/librarySettings' + $ref: '../objects/Library.yaml#/components/schemas/librarySettings' librarySort: - name: sort - in: requestBody - summary: The sort order of the library. description: The sort order of the library. For example, to sort by title use 'sort=media.metadata.title'. - schema: - type: string - example: 'media.metadata.title' + type: string + example: 'media.metadata.title' libraryFilter: - name: filter - in: requestBody - summary: The filter for the library. TODO description: The filter for the library. - schema: - type: string - example: 'media.metadata.title' + type: string + example: 'media.metadata.title' libraryCollapseSeries: - name: collapseSeries - in: requestBody description: Whether to collapse series. - schema: - type: boolean - example: true - default: false + type: boolean + example: true + default: false libraryInclude: - name: include - in: requestBody description: The fields to include in the response. The only current option is `rssfeed`. - schema: - type: string - example: 'rssfeed' + type: string + example: 'rssfeed' responses: library200: description: Library found. @@ -147,31 +93,30 @@ paths: operationId: createLibrary summary: Create a new library on server description: Create a new library on server. - required: [name, folders] tags: - Libraries requestBody: - required: true description: The library object to create. content: application/json: schema: type: object + required: [name, folders] properties: name: - $ref: '#/components/requestBody/libraryName' + $ref: '../objects/Library.yaml#/components/schemas/libraryName' folders: - $ref: '#/components/requestBody/libraryFolders' + $ref: '#/components/schemas/libraryFolders' displayOrder: - $ref: '#/components/requestBody/libraryDisplayOrder' + $ref: '#/components/schemas/libraryDisplayOrder' icon: - $ref: '#/components/requestBody/libraryIcon' + $ref: '#/components/schemas/libraryIcon' mediaType: - $ref: '#/components/requestBody/libraryMediaType' + $ref: '#/components/schemas/libraryMediaType' provider: - $ref: '#/components/requestBody/libraryProvider' + $ref: '#/components/schemas/libraryProvider' settings: - $ref: '#/components/requestBody/librarySettings' + $ref: '#/components/schemas/librarySettings' responses: '200': $ref: '#/components/responses/library200' @@ -211,19 +156,19 @@ paths: type: object properties: name: - $ref: '#/components/requestBody/libraryName' + $ref: '../objects/Library.yaml#/components/schemas/libraryName' folders: - $ref: '#/components/requestBody/libraryFolders' + $ref: '#/components/schemas/libraryFolders' displayOrder: - $ref: '#/components/requestBody/libraryDisplayOrder' + $ref: '#/components/schemas/libraryDisplayOrder' icon: - $ref: '#/components/requestBody/libraryIcon' + $ref: '#/components/schemas/libraryIcon' mediaType: - $ref: '#/components/requestBody/libraryMediaType' + $ref: '#/components/schemas/libraryMediaType' provider: - $ref: '#/components/requestBody/libraryProvider' + $ref: '#/components/schemas/libraryProvider' settings: - $ref: '#/components/requestBody/librarySettings' + $ref: '#/components/schemas/librarySettings' responses: '200': $ref: '#/components/responses/library200' @@ -263,21 +208,21 @@ paths: type: object properties: limit: - $ref: '../schemas.yaml#/components/requestBody/limit' + $ref: '../schemas.yaml#/components/schemas/limit' page: - $ref: '../schemas.yaml#/components/requestBody/page' + $ref: '../schemas.yaml#/components/schemas/page' sort: - $ref: '#/components/requestBody/librarySort' + $ref: '#/components/schemas/librarySort' desc: - $ref: '../schemas.yaml#/components/requestBody/sortDesc' + $ref: '../schemas.yaml#/components/schemas/sortDesc' filter: - $ref: '#/components/requestBody/libraryFilter' + $ref: '#/components/schemas/libraryFilter' minified: - $ref: '../schemas.yaml#/components/requestBody/minified' + $ref: '../schemas.yaml#/components/schemas/minified' collapseSeries: - $ref: '#/components/requestBody/libraryCollapseSeries' + $ref: '#/components/schemas/libraryCollapseSeries' include: - $ref: '#/components/requestBody/libraryInclude' + $ref: '#/components/schemas/libraryInclude' responses: '200': description: getLibraryItems OK diff --git a/docs/objects/Library.yaml b/docs/objects/Library.yaml index 26daf455f..c7a2a52e0 100644 --- a/docs/objects/Library.yaml +++ b/docs/objects/Library.yaml @@ -36,10 +36,8 @@ components: example: false autoScanCronExpression: description: The cron expression for when to automatically scan the library folders. If null, automatic scanning will be disabled. - oneOf: - - type: string - - type: boolean - - type: null + type: string + nullable: true example: '0 0 0 * * *' audiobooksOnly: description: Whether the library should ignore ebook files and only allow ebook files to be supplementary. diff --git a/docs/objects/entities/Author.yaml b/docs/objects/entities/Author.yaml index fe38b4188..838e5b517 100644 --- a/docs/objects/entities/Author.yaml +++ b/docs/objects/entities/Author.yaml @@ -7,15 +7,23 @@ components: example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b authorAsin: description: The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier. - oneOf: - - type: string - - type: null + type: string nullable: true example: B000APZOQA authorName: description: The name of the author. type: string example: Terry Goodkind + authorDescription: + description: The new description of the author. + 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: + description: The absolute path for the author image. This will be in the `metadata/` directory. Will be null if there is no image. + type: string + nullable: true + example: /metadata/authors/aut_z3leimgybl7uf3y4ab.jpg authorSeries: type: object description: Series and the included library items that an author has written. @@ -28,9 +36,8 @@ components: 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' + $ref: '../LibraryItem.yaml#/components/schemas/libraryItemMinified' author: - summary: An author object which includes a description and image path. description: An author object which includes a description and image path. The library items and series associated with the author are optionally included. type: object properties: @@ -41,26 +48,9 @@ components: name: $ref: '#/components/schemas/authorName' description: - description: A description of the author. Will be null if there is none. - oneOf: - - type: string - - type: null - 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. + $ref: '#/components/schemas/authorDescription' imagePath: - description: The absolute path for the author image located in the `metadata/` directory. Will be null if there is no image. - oneOf: - - type: string - - type: null - nullable: true - example: /metadata/authors/aut_bxxbyjiptmgb56yzoz.jpg + $ref: '#/components/schemas/authorImagePath' addedAt: $ref: '../../schemas.yaml#/components/schemas/addedAt' updatedAt: diff --git a/docs/schemas.yaml b/docs/schemas.yaml index 019d954ac..1e4d11f2e 100644 --- a/docs/schemas.yaml +++ b/docs/schemas.yaml @@ -31,27 +31,12 @@ components: type: string format: '[0-9]*' example: '649644248522215260' - limit: - description: The number of items to return from the request. - type: integer - example: 10 total: description: The total number of items in the response. type: integer example: 100 - page: - description: The page number (zero indexed) to return from the request. - type: integer - example: 0 - minified: - description: Whether minified was set in the request. - type: boolean - example: true - requestBody: limit: name: limit - in: requestBody - summary: The number of items to return. description: The number of items to return. If 0, no items are returned. schema: type: integer @@ -59,8 +44,6 @@ components: default: 0 page: name: page - in: requestBody - summary: The page number (zero indexed) to return. description: The page number (zero indexed) to return. If no limit is specified, then page will have no effect. schema: type: integer @@ -68,8 +51,6 @@ components: default: 0 sortDesc: name: desc - in: requestBody - summary: Sort in reverse order. description: Return items in reversed order if true. schema: type: boolean @@ -77,8 +58,6 @@ components: default: false minified: name: minified - in: requestBody - summary: Return minified items. description: Return minified items if true. schema: type: boolean