diff --git a/docs/controllers/LibraryController.yaml b/docs/controllers/LibraryController.yaml index ad48b2c12..b8d440cf3 100644 --- a/docs/controllers/LibraryController.yaml +++ b/docs/controllers/LibraryController.yaml @@ -57,6 +57,32 @@ components: description: The fields to include in the response. The only current option is `rssfeed`. type: string example: 'rssfeed' + parameters: + limit: + in: query + name: limit + description: The number of items to return. This the size of a single page for the optional `page` query. + example: 10 + schema: + type: integer + default: 0 + page: + in: query + name: page + description: The page number (zero indexed) to return. If no limit is specified, then page will have no effect. + example: 0 + schema: + type: integer + default: 0 + desc: + in: query + name: desc + description: Return items in reversed order if true. + example: true + schema: + type: boolean + default: false + responses: library200: description: Library found. @@ -135,6 +161,11 @@ paths: description: Get a single library by ID on server. tags: - Libraries + parameters: + - in: query + name: include + schema: + type: string responses: '200': $ref: '#/components/responses/library200' @@ -222,30 +253,38 @@ paths: description: Get items in a library by ID on server. tags: - Libraries - requestBody: - required: false - description: The filters to apply to the requested library items. - content: - application/json: - schema: - type: object - properties: - limit: - $ref: '../schemas.yaml#/components/schemas/limit' - page: - $ref: '../schemas.yaml#/components/schemas/page' - sort: - $ref: '#/components/schemas/librarySort' - desc: - $ref: '../schemas.yaml#/components/schemas/sortDesc' - filter: - $ref: '#/components/schemas/libraryFilter' - minified: - $ref: '../schemas.yaml#/components/schemas/minified' - collapseSeries: - $ref: '#/components/schemas/libraryCollapseSeries' - include: - $ref: '#/components/schemas/libraryInclude' + parameters: + - $ref: '#/components/parameters/limit' + - $ref: '#/components/parameters/page' + - in: query + name: sort + description: The field to sort by from the request. + example: 'numBooks' + schema: + type: string + enum: ['name', 'numBooks', 'totalDuration', 'addedAt', 'lastBookAdded', 'lastBookUpdated'] + default: 'name' + - $ref: '#/components/parameters/desc' + - in: query + name: filter + description: The filter for the library. + example: 'media.metadata.title' + schema: + type: string + - in: query + name: include + description: The fields to include in the response. The only current option is `rssfeed`. + allowReserved: true + example: 'rssfeed' + schema: + type: string + - $ref: '../schemas.yaml#/components/parameters/minified' + - in: query + name: collapseSeries + description: Whether to collapse series into a single cover + schema: + type: integer + default: 0 responses: '200': description: getLibraryItems OK @@ -323,20 +362,8 @@ paths: tags: - Libraries parameters: - - in: query - name: limit - description: The number of series to return. If 0, all series are returned. - example: 10 - schema: - type: integer - default: 0 - - in: query - name: page - description: The page number (zero indexed) to return. If no limit is specified, then page will have no effect. - example: 0 - schema: - type: integer - default: 0 + - $ref: '#/components/parameters/limit' + - $ref: '#/components/parameters/page' - in: query name: sort description: The field to sort by from the request. @@ -345,13 +372,7 @@ paths: type: string enum: ['name', 'numBooks', 'totalDuration', 'addedAt', 'lastBookAdded', 'lastBookUpdated'] default: 'name' - - in: query - name: desc - description: Return items in reversed order if true. - example: true - schema: - type: boolean - default: false + - $ref: '#/components/parameters/desc' - in: query name: filter description: The filter for the library. @@ -361,6 +382,7 @@ paths: - in: query name: include description: The fields to include in the response. The only current option is `rssfeed`. + allowReserved: true example: 'rssfeed' schema: type: string @@ -416,32 +438,32 @@ paths: deprecated: true tags: - Libraries - requestBody: - required: false - description: The filters to apply to the requested library series. - content: - application/json: - schema: - type: object - properties: - limit: - $ref: '../schemas.yaml#/components/schemas/limit' - page: - $ref: '../schemas.yaml#/components/schemas/page' - sort: - description: The field to sort by from the request. - type: string - enum: ['name', 'numBooks', 'totalDuration', 'addedAt', 'lastBookAdded', 'lastBookUpdated'] - example: 'numBooks' - default: 'name' - desc: - $ref: '../schemas.yaml#/components/schemas/sortDesc' - filter: - $ref: '#/components/schemas/libraryFilter' - minified: - $ref: '../schemas.yaml#/components/schemas/minified' - include: - $ref: '#/components/schemas/libraryInclude' + parameters: + - $ref: '#/components/parameters/limit' + - $ref: '#/components/parameters/page' + - in: query + name: sort + description: The field to sort by from the request. + example: 'numBooks' + schema: + type: string + enum: ['name', 'numBooks', 'totalDuration', 'addedAt', 'lastBookAdded', 'lastBookUpdated'] + default: 'name' + - $ref: '#/components/parameters/desc' + - in: query + name: filter + description: The filter for the library. + example: 'media.metadata.title' + schema: + type: string + - $ref: '../schemas.yaml#/components/parameters/minified' + - in: query + name: include + description: The fields to include in the response. The only current option is `rssfeed`. + allowReserved: true + example: 'rssfeed' + schema: + type: string responses: '200': description: getLibrarySeriesById OK diff --git a/docs/openapi.json b/docs/openapi.json index cb1f14061..0694241b6 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -492,6 +492,15 @@ "tags": [ "Libraries" ], + "parameters": [ + { + "in": "query", + "name": "include", + "schema": { + "type": "string" + } + } + ], "responses": { "200": { "$ref": "#/components/responses/library200" @@ -631,43 +640,66 @@ "tags": [ "Libraries" ], - "requestBody": { - "required": false, - "description": "The filters to apply to the requested library items.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "limit": { - "$ref": "#/components/schemas/limit" - }, - "page": { - "$ref": "#/components/schemas/page" - }, - "sort": { - "$ref": "#/components/schemas/librarySort" - }, - "desc": { - "$ref": "#/components/schemas/sortDesc" - }, - "filter": { - "$ref": "#/components/schemas/libraryFilter" - }, - "minified": { - "$ref": "#/components/schemas/minified" - }, - "collapseSeries": { - "$ref": "#/components/schemas/libraryCollapseSeries" - }, - "include": { - "$ref": "#/components/schemas/libraryInclude" - } - } - } + "parameters": [ + { + "$ref": "#/components/parameters/limit" + }, + { + "$ref": "#/components/parameters/page" + }, + { + "in": "query", + "name": "sort", + "description": "The field to sort by from the request.", + "example": "numBooks", + "schema": { + "type": "string", + "enum": [ + "name", + "numBooks", + "totalDuration", + "addedAt", + "lastBookAdded", + "lastBookUpdated" + ], + "default": "name" + } + }, + { + "$ref": "#/components/parameters/desc" + }, + { + "in": "query", + "name": "filter", + "description": "The filter for the library.", + "example": "media.metadata.title", + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "include", + "description": "The fields to include in the response. The only current option is `rssfeed`.", + "allowReserved": true, + "example": "rssfeed", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/minified" + }, + { + "in": "query", + "name": "collapseSeries", + "description": "Whether to collapse series into a single cover", + "schema": { + "type": "integer", + "default": 0 } } - }, + ], "responses": { "200": { "description": "getLibraryItems OK", @@ -781,24 +813,10 @@ ], "parameters": [ { - "in": "query", - "name": "limit", - "description": "The number of series to return. If 0, all series are returned.", - "example": 10, - "schema": { - "type": "integer", - "default": 0 - } + "$ref": "#/components/parameters/limit" }, { - "in": "query", - "name": "page", - "description": "The page number (zero indexed) to return. If no limit is specified, then page will have no effect.", - "example": 0, - "schema": { - "type": "integer", - "default": 0 - } + "$ref": "#/components/parameters/page" }, { "in": "query", @@ -819,14 +837,7 @@ } }, { - "in": "query", - "name": "desc", - "description": "Return items in reversed order if true.", - "example": true, - "schema": { - "type": "boolean", - "default": false - } + "$ref": "#/components/parameters/desc" }, { "in": "query", @@ -841,6 +852,7 @@ "in": "query", "name": "include", "description": "The fields to include in the response. The only current option is `rssfeed`.", + "allowReserved": true, "example": "rssfeed", "schema": { "type": "string" @@ -925,51 +937,57 @@ "tags": [ "Libraries" ], - "requestBody": { - "required": false, - "description": "The filters to apply to the requested library series.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "limit": { - "$ref": "#/components/schemas/limit" - }, - "page": { - "$ref": "#/components/schemas/page" - }, - "sort": { - "description": "The field to sort by from the request.", - "type": "string", - "enum": [ - "name", - "numBooks", - "totalDuration", - "addedAt", - "lastBookAdded", - "lastBookUpdated" - ], - "example": "numBooks", - "default": "name" - }, - "desc": { - "$ref": "#/components/schemas/sortDesc" - }, - "filter": { - "$ref": "#/components/schemas/libraryFilter" - }, - "minified": { - "$ref": "#/components/schemas/minified" - }, - "include": { - "$ref": "#/components/schemas/libraryInclude" - } - } - } + "parameters": [ + { + "$ref": "#/components/parameters/limit" + }, + { + "$ref": "#/components/parameters/page" + }, + { + "in": "query", + "name": "sort", + "description": "The field to sort by from the request.", + "example": "numBooks", + "schema": { + "type": "string", + "enum": [ + "name", + "numBooks", + "totalDuration", + "addedAt", + "lastBookAdded", + "lastBookUpdated" + ], + "default": "name" + } + }, + { + "$ref": "#/components/parameters/desc" + }, + { + "in": "query", + "name": "filter", + "description": "The filter for the library.", + "example": "media.metadata.title", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/minified" + }, + { + "in": "query", + "name": "include", + "description": "The fields to include in the response. The only current option is `rssfeed`.", + "allowReserved": true, + "example": "rssfeed", + "schema": { + "type": "string" } } - }, + ], "responses": { "200": { "description": "getLibrarySeriesById OK", @@ -1766,6 +1784,11 @@ } ] }, + "total": { + "description": "The total number of items in the response.", + "type": "integer", + "example": 100 + }, "limit": { "description": "The number of items to return. If 0, no items are returned.", "type": "integer", @@ -1778,20 +1801,19 @@ "example": 1, "default": 0 }, - "librarySort": { - "description": "The sort order of the library. For example, to sort by title use 'sort=media.metadata.title'.", + "sortBy": { "type": "string", + "description": "The field to sort by from the request.", "example": "media.metadata.title" }, "sortDesc": { - "description": "Return items in reversed order if true.", + "description": "Whether to sort in descending order.", "type": "boolean", - "example": true, - "default": false + "example": true }, - "libraryFilter": { - "description": "The filter for the library.", + "filterBy": { "type": "string", + "description": "The field to filter by from the request. TODO", "example": "media.metadata.title" }, "minified": { @@ -1800,37 +1822,16 @@ "example": true, "default": false }, - "libraryCollapseSeries": { - "description": "Whether to collapse series.", + "collapseSeries": { "type": "boolean", - "example": true, - "default": false + "description": "Whether collapse series was set in the request.", + "example": true }, "libraryInclude": { "description": "The fields to include in the response. The only current option is `rssfeed`.", "type": "string", "example": "rssfeed" }, - "total": { - "description": "The total number of items in the response.", - "type": "integer", - "example": 100 - }, - "sortBy": { - "type": "string", - "description": "The field to sort by from the request.", - "example": "media.metadata.title" - }, - "filterBy": { - "type": "string", - "description": "The field to filter by from the request. TODO", - "example": "media.metadata.title" - }, - "collapseSeries": { - "type": "boolean", - "description": "Whether collapse series was set in the request.", - "example": true - }, "sequence": { "description": "The position in the series the book is.", "type": "string", @@ -2004,6 +2005,48 @@ } } } + }, + "parameters": { + "limit": { + "in": "query", + "name": "limit", + "description": "The number of items to return. This the size of a single page for the optional `page` query.", + "example": 10, + "schema": { + "type": "integer", + "default": 0 + } + }, + "page": { + "in": "query", + "name": "page", + "description": "The page number (zero indexed) to return. If no limit is specified, then page will have no effect.", + "example": 0, + "schema": { + "type": "integer", + "default": 0 + } + }, + "desc": { + "in": "query", + "name": "desc", + "description": "Return items in reversed order if true.", + "example": true, + "schema": { + "type": "boolean", + "default": false + } + }, + "minified": { + "in": "query", + "name": "minified", + "description": "Return minified items if true", + "schema": { + "type": "integer", + "minimum": 0, + "example": 1 + } + } } } } diff --git a/docs/schemas.yaml b/docs/schemas.yaml index 6b371892f..072895616 100644 --- a/docs/schemas.yaml +++ b/docs/schemas.yaml @@ -60,3 +60,12 @@ components: type: string example: 'us' default: 'us' + parameters: + minified: + in: query + name: minified + description: Return minified items if true + schema: + type: integer + minimum: 0 + example: 1