diff --git a/docs/controllers/MeController.yaml b/docs/controllers/MeController.yaml index e8165b322..b461ea886 100644 --- a/docs/controllers/MeController.yaml +++ b/docs/controllers/MeController.yaml @@ -1,3 +1,9 @@ +components: + schemas: + totalTime: + description: The total time listened in seconds. + type: integer + example: 123456 paths: /api/me: get: @@ -75,3 +81,127 @@ paths: schema: type: string example: Not Found + /api/me/listening-sessions: + get: + operationId: getListeningSessions + summary: Get all listening sessions for the current user. + description: Get all listening sessions for the current user. + tags: + - Me + parameters: + - name: itemsPerPage + in: query + description: The number of items per page. + required: true + schema: + $ref: '../schemas.yaml#/components/schemas/limit' + - name: page + in: query + description: The page number (zero indexed) to return. + required: true + schema: + $ref: '../schemas.yaml#/components/schemas/page' + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + total: + $ref: '../schemas.yaml#/components/schemas/total' + numPages: + description: The number of pages. + type: integer + itemsPerPage: + $ref: '../schemas.yaml#/components/schemas/limit' + sessions: + type: array + items: + $ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSession' + /api/me/items-in-progress: + get: + operationId: getItemsInProgress + summary: Get all items in progress for the current user. + description: Get all items in progress for the current user. + tags: + - Me + parameters: + - name: limit + in: query + description: The number of items to return. + required: false + schema: + $ref: '../schemas.yaml#/components/schemas/limit' + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + total: + $ref: '../schemas.yaml#/components/schemas/total' + numPages: + description: The number of pages. + type: integer + itemsPerPage: + $ref: '../schemas.yaml#/components/schemas/limit' + items: + type: array + items: + $ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItemMinified' + /api/me/listening-stats: + get: + operationId: getListeningStats + summary: Get listening stats for the current user. + description: Get listening stats for the current user. + tags: + - Me + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + totalTime: + $ref: '#/components/schemas/totalTime' + items: + type: object + description: A list of library items the user has listened to, keyed by their item IDs. + additionalProperties: + type: object + properties: + id: + type: string + description: The ID of the library item. + timeListening: + type: integer + description: The time (in seconds) the user listened to this library item. + mediaMetadata: + oneOf: + - $ref: '../objects/metadata/BookMetadata.yaml#/components/schemas/bookMetadata' + - $ref: '../objects/metadata/PodcastMetadata.yaml#/components/schemas/PodcastMetadata' + days: + type: object + description: A mapping of days to total listening times. + additionalProperties: + type: integer + description: The total time (in seconds) listened to on that day. + dayOfWeek: + type: object + description: A mapping of days of the week to total listening times. + additionalProperties: + type: integer + description: The total time (in seconds) listened to on that day of the week. + today: + type: integer + description: The time (in seconds) the user has listened to library items today. + recentSessions: + type: array + items: + $ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSession' diff --git a/docs/controllers/SessionController.yaml b/docs/controllers/SessionController.yaml index 70cab2843..3a1f17057 100644 --- a/docs/controllers/SessionController.yaml +++ b/docs/controllers/SessionController.yaml @@ -53,3 +53,173 @@ paths: schema: type: string example: Internal Server Error + /api/sessions/{id}: + delete: + operationId: deleteSession + summary: Delets a listening session. + description: Deletes a listening session. + tags: + - Session + parameters: + - name: id + in: path + description: The ID of the session. + required: true + schema: + $ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSessionId' + responses: + '200': + description: OK + content: + html/text: + schema: + type: string + example: OK + '403': + description: A user with delete permissions is required to delete sessions. + content: + html/text: + schema: + type: string + example: Forbidden + '404': + description: No listening session with the provided ID was found. + content: + html/text: + schema: + type: string + example: Not Found + /api/session/{id}/close: + post: + operationId: closeSession + summary: Close a listening session. + description: Close a listening session. + tags: + - Session + parameters: + - name: id + in: path + description: The ID of the session. + required: true + schema: + $ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSessionId' + - name: currentTime + in: query + description: The current time of the session. + required: false + schema: + $ref: '../schemas.yaml#/components/schemas/durationSec' + - name: timeListened + in: query + description: The time listened to the session. + required: false + schema: + $ref: '../schemas.yaml#/components/schemas/durationSec' + - name: duration + in: query + description: The duration of the session. + required: false + schema: + $ref: '../schemas.yaml#/components/schemas/durationSec' + responses: + '200': + description: OK + content: + html/text: + schema: + type: string + example: OK + '404': + description: No listening session with the provided ID is open, or the session belongs to another user. + content: + html/text: + schema: + type: string + example: Not Found + /api/session/{id}: + get: + operationId: getSession + summary: Get a listening session. + description: Get a listening session. + tags: + - Session + parameters: + - name: id + in: path + description: The ID of the session. + required: true + schema: + $ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSessionId' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSessionExpanded' + '404': + description: No listening session with the provided ID was found. + content: + html/text: + schema: + type: string + example: Not Found + /api/sessions: + get: + operationId: getSessions + summary: Get all listening sessions. + description: Get all listening sessions. + tags: + - Session + parameters: + - name: user + in: query + description: The ID of the user to filter listening sessions by. + required: false + schema: + $ref: '../objects/entities/User.yaml#/components/schemas/userId' + - name: itemsPerPage + in: query + description: The number of items to return. + required: false + schema: + $ref: '../schemas.yaml#/components/schemas/limit' + - name: page + in: query + description: The page number (zero indexed) to return. + required: false + schema: + $ref: '../schemas.yaml#/components/schemas/page' + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + results: + type: array + items: + $ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItemBase' + total: + $ref: '../schemas.yaml#/components/schemas/total' + itemsPerPage: + $ref: '../schemas.yaml#/components/schemas/limit' + numPages: + description: The number of pages. + type: integer + example: 10 + userFilter: + description: If provided, the `user` parameter. + sessions: + type: array + items: + $ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSession' + '404': + description: No listening sessions were found. + content: + html/text: + schema: + type: string + example: Not Found diff --git a/docs/openapi.json b/docs/openapi.json index c5edd2706..97ce3d814 100644 Binary files a/docs/openapi.json and b/docs/openapi.json differ diff --git a/docs/root.yaml b/docs/root.yaml index 63462a22c..b93d88a68 100644 --- a/docs/root.yaml +++ b/docs/root.yaml @@ -93,6 +93,18 @@ paths: $ref: './controllers/MeController.yaml#/paths/~1api~1me~1progress~1{mediaId}' /api/session/{id}/sync: $ref: './controllers/SessionController.yaml#/paths/~1api~1session~1{id}~1sync' + /api/sessions/{id}: + $ref: './controllers/SessionController.yaml#/paths/~1api~1sessions~1{id}' + /api/session/{id}/close: + $ref: './controllers/SessionController.yaml#/paths/~1api~1session~1{id}~1close' + /api/session/{id}: + $ref: './controllers/SessionController.yaml#/paths/~1api~1session~1{id}' + /api/sessions: + $ref: './controllers/SessionController.yaml#/paths/~1api~1sessions' + /api/me/listening-sessions: + $ref: './controllers/MeController.yaml#/paths/~1api~1me~1listening-sessions' + /api/me/listening-stats: + $ref: './controllers/MeController.yaml#/paths/~1api~1me~1listening-stats' tags: - name: Authors description: Author endpoints @@ -106,3 +118,9 @@ tags: description: Notifications endpoints - name: Podcasts description: Podcast endpoints + - name: Auth + description: Authentication endpoints + - name: Me + description: User endpoints + - name: Session + description: Session endpoints