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

Update OpenAPI readme

Browse source
This commit is contained in:
Nicholas Wallace 2024-05-25 20:37:51 +00:00
parent a7a68a00dd
commit e17cf99ac4
1 changed files with 20 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

37
docs/README.md
View file

@ -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 command to convert the spec using `yq` is `yq -p yaml -o json openapi.yaml > openapi.json`.
The `yq` tool is used to convert the `yaml` to a `json` using the `yq -p yaml -o json bundled.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.
### 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 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
```