Initial CollectionController OpenAPI spec

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.

server/controllers/CollectionController.js

@@ -9,10 +9,40 @@ class CollectionController {
   constructor() { }
 
   /**
-   * POST: /api/collections
+   * @openapi
-   * Create new collection
+   * /api/collections:
-   * @param {*} req 
+   *   post:
-   * @param {*} res 
+   *     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
+   * @openapi
-   * Update collection
+   * /api/collections/{id}:
-   * @param {*} req 
+   *   patch:
-   * @param {*} res 
+   *     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) {

server/controllers/LibraryController.js

@@ -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)
 

server/controllers/LibraryItemController.js

@@ -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) {

server/models/Collection.js

@@ -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)