audiobookshelf/docs
Nicholas W 7d05317357
Notification endpoints (#3096)
* Initial notification schema

* Add: notification event and settings schema

* Add: NotificationController

* Update bundled spec

* Fix: `operationId` typos

* Fix: library response to be arroy of objects

* Fix: notification ID is not uuid

* Add: `nullable` notification creation parameters

* Nullable libraryId schema

* Remove: `id` from Notification requestBody

* Fix: `allOf` for `libraryItemSequence`

* Fix: required `id` in wrong body

* Fix: libraryItem typos

* Update: bundled spec
2024-06-23 14:12:10 -05:00
..
controllers Notification endpoints (#3096) 2024-06-23 14:12:10 -05:00
objects Notification endpoints (#3096) 2024-06-23 14:12:10 -05:00
openapi.json Notification endpoints (#3096) 2024-06-23 14:12:10 -05:00
README.md Initial library endpoints (#3012) 2024-06-13 17:09:02 -05:00
root.yaml Notification endpoints (#3096) 2024-06-23 14:12:10 -05:00
schemas.yaml Change: requestBody to parameter, allow commas in queries 2024-06-21 22:25:22 +00:00

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 using redocly-cli. This tool also generates HTML docs for the spec.

The tools created by pb33f, 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 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 used to lint the spec is redocly lint root.yaml

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 documentation is:

redocly bundle root.yaml > bundled.yaml && \
yq -p yaml -o json bundled.yaml > openapi.json && \
redocly build-docs openapi.json