From ca7eaf97502676f0933925ad9450396f0c18161f Mon Sep 17 00:00:00 2001 From: Nicholas Wallace Date: Mon, 1 Apr 2024 00:44:51 +0000 Subject: [PATCH] OpenAPI spec readme --- docs/README.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..c6f278ed --- /dev/null +++ b/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 +```