OpenAPI Spec, try 2

docs/README.md

@@ -0,0 +1,30 @@
+# OpenAPI specification
+
+This directory includes the OpenAPI spec for the ABS server.
+The spec is made up of a number of individual `yaml` files located here and in the subfolders, with `root.yaml` being the file that references all of the others.
+The files are organized to have the same hierarchy as the server source files.
+The full spec is bundled into one file in `openapi.json`.
+
+The spec is linted and bundled by the [`vacuum` tool](https://quobix.com/vacuum/).
+The spec can also be tested with a real server using the [`wiretap` tool](https://pb33f.io/wiretap/).
+Both of these tools are created by [pb33f](https://pb33f.io/).
+
+### Bundling the spec
+The command to bundle the spec into a `yaml` file is `vacuum bundle root.yaml openapi.yaml`.
+
+The current version of `vacuum` cannot convert input `yaml` files to `json` files.
+To convert the spec to `json`, you can use the `yq` tool or another tool.
+
+The command to convert the spec using `yq` is `yq -p yaml -o json openapi.yaml > openapi.json`.
+
+### Viewing report
+To generate an HTML report, you can use `vacuum html-report [file]` to generate `report.html` and view the report in your browser.
+
+### Putting it all together
+The full command that I run to bundle the spec and generate the report is:
+
+```
+vacuum bundle root.yaml openapi.yaml && \
+yq -p yaml -o json openapi.yaml > openapi.json && \
+vacuum html-report openapi.json
+```

docs/controllers/AuthorController.yaml

@@ -0,0 +1,139 @@
+components:
+  schemas:
+    authorUpdated:
+      description: Whether the author was updated without errors. Will not exist if author was merged.
+      type: boolean
+      nullable: true
+  parameters:
+    authorId:
+      name: id
+      in: path
+      description: Author ID
+      required: true
+      schema:
+        $ref: '../objects/entities/Author.yaml#/components/schemas/authorId'
+    authorInclude:
+      name: include
+      in: query
+      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.
+      required: false
+      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"
+    authorLibraryId:
+      name: library
+      in: query
+      description: The ID of the library to to include filter included items from.
+      required: false
+      schema:
+        $ref: '../objects/Library.yaml#/components/schemas/libraryId'
+    asin:
+      name: asin
+      in: query
+      description: The Audible Identifier (ASIN).
+      required: false
+      schema:
+        $ref: '../objects/entities/Author.yaml#/components/schemas/authorAsin'
+    authorSearchName:
+      name: q
+      in: query
+      description: The name of the author to use for searching.
+      required: false
+      schema:
+        type: string
+        example: Terry Goodkind
+    authorName:
+      name: name
+      in: query
+      description: The new name of the author.
+      required: false
+      schema:
+        $ref: '../objects/entities/Author.yaml#/components/schemas/authorName'
+    authorDescription:
+      name: description
+      in: query
+      description: The new description of the author.
+      required: false
+      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.
+    authorImagePath:
+      name: imagePath
+      in: query
+      description: The new absolute path for the author image.
+      required: false
+      schema:
+        type: string
+        nullable: true
+        example: /metadata/authors/aut_z3leimgybl7uf3y4ab.jpg
+    imageUrl:
+      name: url
+      in: query
+      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
+    imageWidth:
+      name: width
+      in: query
+      description: The requested width of image in pixels.
+      schema:
+        type: integer
+        default: 400
+        example: 400
+      example: 400
+    imageHeight:
+      name: height
+      in: query
+      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
+    imageFormat:
+      name: format
+      in: query
+      description: The requested output format.
+      schema:
+        type: string
+        default: jpeg
+        example: webp
+    imageRaw:
+      name: raw
+      in: query
+      description: Return the raw image without scaling if true.
+      schema:
+        type: boolean
+        default: false
+  responses: 
+    author404:
+      description: Author not found.
+      content:
+        text/html:
+          schema:
+            type: string
+            example: Not found
+tags:
+  - name: Authors
+    description: Author endpoints

docs/objects/Folder.yaml

@@ -0,0 +1,21 @@
+components:
+  schemas:
+    folderId:
+      type: string
+      description: The ID of the folder.
+      format: uuid
+      example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
+    folder:
+      type: object
+      description: Folder used in library
+      properties:
+        id:
+          $ref: '#/components/schemas/folderId'
+        fullPath:
+          description: The path on the server for the folder. (Read Only)
+          type: string
+          example: /podcasts
+        libraryId:
+          $ref: './Library.yaml#/components/schemas/libraryId'
+        addedAt:
+          $ref: '../schemas.yaml#/components/schemas/addedAt'

docs/objects/Library.yaml

@@ -0,0 +1,12 @@
+components:
+  schemas:
+    oldLibraryId:
+      type: string
+      description: The ID of the libraries created on server version 2.2.23 and before.
+      format: "lib_[a-z0-9]{18}"
+      example: lib_o78uaoeuh78h6aoeif
+    libraryId:
+      type: string
+      description: The ID of the library.
+      format: uuid
+      example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b

docs/objects/LibraryItem.yaml

@@ -0,0 +1,66 @@
+components:
+  schemas:
+    oldLibraryItemId:
+      description: The ID of library items on server version 2.2.23 and before.
+      type: string
+      nullable: true
+      format: "li_[a-z0-9]{18}"
+      example: li_o78uaoeuh78h6aoeif
+    libraryItemId:
+      type: string
+      description: The ID of library items after 2.3.0.
+      format: uuid
+      example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
+    libraryItemBase:
+      type: object
+      description: Base library item schema
+      properties:
+        id:
+          $ref: '#/components/schemas/libraryItemId'
+        oldLibraryItemId:
+          $ref: '#/components/schemas/oldLibraryItemId'
+        ino:
+          $ref: '../schemas.yaml#/components/schemas/inode'
+        libraryId:
+          $ref: './Library.yaml#/components/schemas/libraryId'
+        folderId:
+          $ref: './Folder.yaml#/components/schemas/folderId'
+        path:
+          description: The path of the library item on the server.
+          type: string
+        relPath:
+          description: The path, relative to the library folder, of the library item.
+          type: string
+        isFile:
+          description: Whether the library item is a single file in the root of the library folder.
+          type: boolean
+        mtimeMs:
+          description: The time (in ms since POSIX epoch) when the library item was last modified on disk.
+          type: integer
+        ctimeMs:
+          description: The time (in ms since POSIX epoch) when the library item status was changed on disk.
+          type: integer
+        birthtimeMs:
+          description: The time (in ms since POSIX epoch) when the library item was created on disk. Will be 0 if unknown.
+          type: integer
+        addedAt:
+          $ref: '../schemas.yaml#/components/schemas/addedAt'
+        updatedAt:
+          $ref: '../schemas.yaml#/components/schemas/updatedAt'
+        isMissing:
+          description: Whether the library item was scanned and no longer exists.
+          type: boolean
+        isInvalid:
+          description: Whether the library item was scanned and no longer has media files.
+          type: boolean
+        mediaType:
+          $ref: './mediaTypes/media.yaml#/components/schemas/mediaType'
+    libraryItemMinified:
+      type: object
+      description: A single item on the server, like a book or podcast. Minified media format.
+      allOf:
+        - $ref : '#/components/schemas/libraryItemBase'
+        - type: object
+          properties:
+            media:
+              $ref: './mediaTypes/media.yaml#/components/schemas/mediaMinified'

docs/objects/entities/Author.yaml

@@ -0,0 +1,104 @@
+components:
+  schemas:
+    authorId:
+      type: string
+      description: The ID of the author.
+      format: uuid
+      example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
+    authorAsin:
+      type: string
+      description: The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.
+      nullable: true
+      example: B000APZOQA
+    authorName:
+      description: The name of the author.
+      type: string
+      example: Terry Goodkind
+    authorSeries:
+      type: object
+      description: Series and the included library items that an author has written.
+      properties:
+        id:
+          $ref: './Series.yaml#/components/schemas/seriesId'
+        name:
+          $ref: './Series.yaml#/components/schemas/seriesName'
+        items:
+          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'
+    author:
+      description: An author object which includes a description and image path.
+      type: object
+      properties:
+        id:
+          $ref: '#/components/schemas/authorId'
+        asin:
+          $ref: '#/components/schemas/authorAsin'
+        name:
+          $ref: '#/components/schemas/authorName'
+        description:
+          description: A description of the author. Will be null if there is none.
+          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. 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.
+        imagePath:
+          description: The absolute path for the author image located in the `metadata/` directory. Will be null if there is no image.
+          type: string
+          nullable: true
+          example: /metadata/authors/aut_bxxbyjiptmgb56yzoz.jpg
+        addedAt:
+          $ref: '../../schemas.yaml#/components/schemas/addedAt'
+        updatedAt:
+          $ref: '../../schemas.yaml#/components/schemas/updatedAt'
+    authorWithItems:
+      type: object
+      description: The author schema with an array of items they are associated with.
+      allOf:
+        - $ref: '#/components/schemas/author'
+        - type: object
+          properties:
+            libraryItems:
+              description: The items associated with the author
+              type: string
+              type: array
+              items:
+                $ref: '../LibraryItem.yaml#/components/schemas/libraryItemMinified'
+    authorWithSeries:
+      type: object
+      description: The author schema with an array of items and series they are associated with.
+      allOf:
+        - $ref: '#/components/schemas/authorWithItems'
+        - type: object
+          properties:
+            series:
+              description: The series associated with the author
+              type: array
+              items:
+                $ref: '#/components/schemas/authorSeries'
+    authorMinified:
+      type: object
+      description: Minified author object which only contains the author name and ID.
+      properties:
+        id:
+          $ref: '#/components/schemas/authorId'
+        name:
+          $ref: '#/components/schemas/authorName'
+    authorExpanded:
+      type: object
+      description: The author schema with the total number of books in the library.
+      allOf:
+        - $ref: '#/components/schemas/author'
+        - type: object
+          properties:
+            numBooks:
+              description: The number of books associated with the author in the library.
+              type: integer
+              example: 1

docs/objects/entities/Series.yaml

@@ -0,0 +1,11 @@
+components:
+  schemas:
+    seriesId:
+      type: string
+      description: The ID of the series.
+      format: uuid
+      example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
+    seriesName:
+      description: The name of the series.
+      type: string
+      example: Sword of Truth