-
Notifications
You must be signed in to change notification settings - Fork 466
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
30 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
``` |