Initial library endpoints (#3012)

* Fix: extra type in `Author.yaml`

* Fix: formatting

* Initial library schema

* Additional debugging

* Fix: spec relative paths

* Add: ebook file spec

* Fix: response type should be string

* Linting updates

* Add: missing librarySettings

* Temporary fix: Library cron can be null or false

* Author controller updates

* Add: `/api/libraries/{id}` endpoint

* Update library responses

* Add: descriptions

* Fix: queries should be in body

* Fix: `body` should be `requestBody`

* Move: `libraryController` paths, clean up `requestBody`

* Clean up libraryController parameters

* Move: author endpoints to controller

* Add `get` for author images

* Simplify author schema with items

* Remove: unused response type

* Update: formatting

* Update json

* Update requestBody on LibraryController

* LibrarySettings update

* Replace: generic parameter with path specific parameter

* Fix: requestBody descriptions

* Fix: match post operation

* Temporary: nullable Author schemas

* LibraryController items endpoint

* Add: delete library items with issues

* Massive cleanup and violation fixing

* Update bundled spec

* Add: remove library items with issues

* Add: library items endpoint

* Fix: errors

* Fix: base schemas

* Add: series schemas

* Add: library series endpoint

* Fix: oneOf and array issues

* Add: author search region for matching

* Add: series endpoints

* Fix: series issues

* Add library series endpoint and update deprecation

* Fix: series endpoint deprecation

* Fix: `name` in `sortDesc` schema

* Add: workflow for linting spec

* Update OpenAPI readme

.github/workflows/lint-openapi.yml

@@ -0,0 +1,30 @@
+name: API linting
+
+# Run on pull requests or pushes when there is a change to the OpenAPI file
+on:
+  push:
+    paths:
+      - docs/
+  pull_request:
+    paths:
+      - docs/
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      # Check out the repository
+      - name: Checkout
+        uses: actions/checkout@v4
+      # Set up node to run the javascript
+      - name: Set up node
+        uses: actions/setup-node@v4
+      # Install Redocly CLI
+      - name: Install Redocly CLI
+        run: npm install -g @redocly/cli@latest
+      # Perform linting for exploded spec
+      - name: Run linting for exploded spec
+        run: redocly lint docs/root.yaml --format=github-actions
+      # Perform linting for bundled spec
+      - name: Run linting for bundled spec
+        run: redocly lint docs/openapi.json --format=github-actions

docs/README.md

@@ -1,30 +1,33 @@
 # 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`.
+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/).
+The spec is linted and bundled using [`redocly-cli`](https://redocly.com/docs/cli/). This tool also generates HTML docs for the spec.
+
+The tools created by [`pb33f`](https://pb33f.io/), specifically `vacuum` and `wiretap`, are also useful for linting and verification. These tools check for some other things, such as validating requests to and responses from the server.
 
 ### 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 used to bundle the spec into a `yaml` file is `redocly bundle root.yaml > bundled.yaml`.
+
+The `yq` tool is used to convert the `yaml` to a `json` using the `yq -p yaml -o json bundled.yaml > openapi.json`.
+
+### Linting the spec
 
-The command to convert the spec using `yq` is `yq -p yaml -o json openapi.yaml > openapi.json`.
+The command used to lint the spec is `redocly lint root.yaml`
 
-### 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.
+To generate an HTML report using `vacuum`, you can use `vacuum html-report [file]` to generate `report.html` and view the report in your browser.
+
+### Generating documentation
+
+Redocly allows for creating a static HTML page to document the API. This is done by using `redocly build-docs [file]` and supports exploded specs.
 
 ### Putting it all together
-The full command that I run to bundle the spec and generate the report is:
+
+The full command that I run to bundle the spec and generate the documentation is:
 
 ```
-vacuum bundle root.yaml openapi.yaml && \
-yq -p yaml -o json openapi.yaml > openapi.json && \
-vacuum html-report openapi.json
+redocly bundle root.yaml > bundled.yaml && \
+yq -p yaml -o json bundled.yaml > openapi.json && \
+redocly build-docs openapi.json
 ```