groove/audiobookshelf
1
0
Fork 0
mirror of https://github.com/advplyr/audiobookshelf.git synced 2026-07-12 12:21:34 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Initial CollectionController OpenAPI spec

Browse source 
This includes a large `components.js` taken from initial efforts of
benonymity. This file still needs to be cleaned up but is provided
as a starting point.
This commit is contained in:
Nicholas Wallace 2024-02-17 03:50:37 +00:00
parent 4c11ca5a55
commit f41b1b6469
5 changed files with 4105 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

170
server/controllers/CollectionController.js
View file

@ -9,10 +9,40 @@ class CollectionController {
constructor() { }
/**
* POST: /api/collections
* Create new collection
* @param {*} req
* @param {*} res
* @openapi
* /api/collections:
* post:
* operationId: createCollection
* summary: Create a new collection
* tags:
* - Collections
* requestBody:
* description: Data for creating a new collection
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* name:
* type: string
* description:
* type: string
* books:
* type: array
* items:
* type: string
* required:
* name
* responses:
* 200:
* description: Collection created successfully
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/collection'
* 400:
* description: Invalid collection data
*/
async create(req, res) {
const newCollection = new Collection()
@ -48,7 +78,23 @@ class CollectionController {
SocketAuthority.emitter('collection_added', jsonExpanded)
res.json(jsonExpanded)
}
/**
* @openapi
* /api/collections:
* get:
* operationId: getAllCollections
* summary: Get all collections
* deprecated: true
* tags:
* - Collections
* responses:
* 200:
* description: Collection created successfully
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/collectionExpanded'
*/
async findAll(req, res) {
const collectionsExpanded = await Database.collectionModel.getOldCollectionsJsonExpanded(req.user)
res.json({
@ -69,10 +115,49 @@ class CollectionController {
}
/**
* PATCH: /api/collections/:id
* Update collection
* @param {*} req
* @param {*} res
* @openapi
* /api/collections/{id}:
* patch:
* operationId: updateCollection
* summary: Update an existing collection
* tags:
* - Collections
* parameters:
* - name: id
* in: path
* description: Collection ID
* required: true
* schema:
* type: string
* requestBody:
* description: Data for updating an existing collection
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* libraryId:
* type: string
* name:
* type: string
* description:
* type: [string, null]
* books:
* type: array
* items:
* type: string
* responses:
* 200:
* description: Collection created successfully
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/collectionExpanded'
* 403:
* A user with update permissions is required to update collections
* 404:
* description: No collection with the specified ID exists
*/
async update(req, res) {
let wasUpdated = false
@ -122,7 +207,29 @@ class CollectionController {
}
res.json(jsonExpanded)
}
/**
* @openapi
* /api/collections/{id}:
* delete:
* operationId: deleteCollection
* summary: Delete specified collection
* tags:
* - Collections
* parameters:
* - name: id
* in: path
* description: Collection ID
* required: true
* schema:
* type: string
* responses:
* 200:
* description: Collection created successfully
* 403:
* description: A user with delete permissions is required to delete a collection
* 404:
* description: No collection with the specified ID exists
*/
async delete(req, res) {
const jsonExpanded = await req.collection.getOldJsonExpanded()
@ -142,6 +249,49 @@ class CollectionController {
* @param {*} req
* @param {*} res
*/
/**
* @openapi
* /api/collections/{id}/book:
* post:
* operationId: collectionAddBook
* summary: Add a single book to a collection
* tags:
* - Collections
* parameters:
* - name: id
* in: path
* description: Collection ID
* required: true
* schema:
* type: string
* requestBody:
* description: Data for adding a single book to a collection
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* libraryId:
* type: string
* books:
* type: array
* items:
* type: string
* responses:
* 200:
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/collectionExpanded'
* 403:
* A user with update permissions is required to update collections
* 404:
* description: No collection with the specified ID exists
* 500:
* description: The provided library ID could not be found, is in
* a different library, or is already in a collection
*/
async addBook(req, res) {
const libraryItem = await Database.libraryItemModel.getOldById(req.body.id)
if (!libraryItem) {

25
server/controllers/LibraryController.js
View file

@ -451,6 +451,31 @@ class LibraryController {
* @param {*} req
* @param {*} res
*/
/**
* @openapi
* /api/libraries/{id}/collections:
* get:
* operationId: getLibraryCollections
* summary: Get all collections in a library
* tags:
* - Library
* parameters:
* - name: id
* in: path
* description: Library ID
* required: true
* schema:
* type: string
* responses:
* 200:
* description: Collection created successfully
* content:
* application/json:
* schema:
* type: array
* items:
* $ref: '#/components/schemas/collectionExpanded'
*/
async getCollectionsForLibrary(req, res) {
const include = (req.query.include || '').split(',').map(v => v.trim().toLowerCase()).filter(v => !!v)

24
server/controllers/LibraryItemController.js
View file

@ -26,6 +26,30 @@ class LibraryItemController {
* @param {import('express').Request} req
* @param {import('express').Response} res
*/
/**
* @openapi
* /api/items/{id}:
* get:
* summary: Get a library item
* tags:
* - Items
* parameters:
* - name: id
* in: path
* description: Library Item ID
* required: true
* schema:
* type: string
* responses:
* 200:
* description: Got the library item
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/libraryItem'
* 400:
* description: Invalid collection data
*/
async findOne(req, res) {
const includeEntities = (req.query.include || '').split(',')
if (req.query.expanded == 1) {

62
server/models/Collection.js
View file

@ -2,7 +2,67 @@ const { DataTypes, Model, Sequelize } = require('sequelize')
const oldCollection = require('../objects/Collection')
/**
* @openapi
* components:
* schemas:
* collection:
* type: object
* description: A public collection of library items which can be ordered and has a description.
* properties:
* id:
* description: The ID of the collection.
* type: string
* libraryId:
* description: The ID of the library the collection belongs to.
* type: string
* name:
* description: The name of the collection.
* type: string
* description:
* description: The description of the collection.
* type: [string, null]
* books:
* description: The books that belong to the collection.
* type: array
* items:
* $ref: '#/components/schemas/libraryItem'
* lastUpdate:
* description: The time (in ms since POSIX epoch) when the collection was last updated.
* type: integer
* createdAt:
* description: The time (in ms since POSIX epoch) when the collection was created.
* type: integer
* collectionExpanded:
* type: object
* properties:
* id:
* description: The ID of the collection.
* type: string
* libraryId:
* description: The ID of the library the collection belongs to.
* type: string
* userId:
* description: The ID of the user that created the collection.
* type: string
* name:
* description: The name of the collection.
* type: string
* description:
* description: The name of the collection.
* type: [string, null]
* books:
* description: The books that belong to the collection.
* type: array
* items:
* $ref: '#/components/schemas/libraryItemExpanded'
* lastUpdate:
* description: The time (in ms since POSIX epoch) when the collection was last updated.
* type: integer
* createdAt:
* description: The time (in ms since POSIX epoch) when the collection was created.
* type: integer
*/
class Collection extends Model {
constructor(values, options) {
super(values, options)

3835
server/models/components.js Normal file
View file

File diff suppressed because it is too large Load diff