apitypes: openapi spec

.gitattributes

@@ -1,2 +1,3 @@
 cmd/build.go export-subst
 *.go diff=golang
+Documentation/reference/api.md linguist-generated

.github/workflows/main.yml

@@ -38,11 +38,6 @@ jobs:
             printf '::error file=%s,title=Bad Filename::Disallowed character in file name\n' "$file"
           done
           exit $(git ls-files -- ':/:*[<>:"|?*]*' | wc -l)
-      - name: Check API Reference
-        if: ${{ !cancelled() && steps.checkout.conclusion == 'success' }}
-        run: |
-          npx widdershins --search false --language_tabs 'python:Python' 'go:Golang' 'javascript:Javascript' --summary ./openapi.yaml -o ./Documentation/reference/api.md
-          git diff --exit-code
       - name: Check Container Versions
         if: ${{ !cancelled() && steps.checkout.conclusion == 'success' }}
         run: |

Documentation/SUMMARY.md

@@ -18,6 +18,7 @@
   - [Building](./contribution/building.md)
   - [Commit Style](./contribution/commit_style.md)
   - [Releases](./contribution/releases.md)
+  - [OpenAPI](./contribution/openapi.md)
 - [Reference](./reference.md)
   - [Api](./reference/api.md)
   - [Clairctl](./reference/clairctl.md)

Documentation/contribution.md

@@ -4,3 +4,4 @@ The following sections provides information on how to contribute to Clair.
 - [Building](./contribution/building.md)
 - [Commit Style](./contribution/commit_style.md)
 - [Releases](./contribution/releases.md)
+- [OpenAPI](./contribution/openapi.md)

Documentation/contribution/openapi.md

@@ -0,0 +1,40 @@
+# OpenAPI
+
+The [OpenAPI specification] has moved from `openapi.yaml` to the `openapi.json`
+and `openapi.yaml` files in `httptransport/api/v1`.
+
+These files are autogenerated from files in `httptransport/api` and
+`httptransport/types` via the `httptransport/api/openapi.zsh` script. This
+script requires `zsh` to run and `sha256sum`, `git`, `jq`, `yq`, and `npx`
+commands in `PATH`.
+
+## Modifications
+
+To modify the OpenAPI spec, edit the relevant `httptransport/api/*/openapi.jq`
+file (a [`jq`] script) or the `httptransport/api/lib/oapi.jq` library as needed,
+then run `go generate ./httptransport`.
+
+The `go generate` command also needs to be run if files in `httptransport/types`
+are modified.
+
+## Script
+
+The `openapi.zsh` script works by:
+- for each `v*` directory under `httptransport/api`:
+  - for all [JSON Schema] files in the corresponding `httptransport/types/v*` directory:
+    - lint the schema
+    - slip-steam examples from the corresponding `examples` file
+  - amalgamate all the files from the previous step
+  - run the `openapi.jq` script with `null` input
+  - merge the outputs of the previous two steps
+  - ~~validate and lint the OpenAPI spec~~[^note]
+  - generate a `yaml` representation
+  - write out a `sha256` checksum in [Etag] format
+
+[^note]: The OpenAPI spec _should_ also be validated or linted, but there's not a known tool that handles JSON Schema [reference resolution] correctly.
+
+[OpenAPI specification]: https://spec.openapis.org/oas/v3.1.0.html
+[`jq`]: https://jqlang.org/manual/
+[JSON Schema]: https://json-schema.org/
+[Etag]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/ETag
+[reference resolution]: https://www.learnjsonschema.com/2020-12/core/ref/

Documentation/howto/api.md

@@ -1,6 +1,6 @@
 # API Definition
 
-Clair provides its API definition via an OpenAPI specification. You can view our OpenAPI spec [here](https://raw.githubusercontent.com/quay/clair/main/openapi.yaml)
+Clair provides its API definition via an OpenAPI specification. You can view our OpenAPI spec [here][openapi_v1].
 
 The OpenAPI spec can be used in a variety of ways.
 * Generating http clients for your application
@@ -11,3 +11,5 @@ The OpenAPI spec can be used in a variety of ways.
 See [Testing Clair](./testing.md) to learn how the local dev tooling starts a local swagger editor. This is handy for making changes to the spec in real time.
 
 See [API Reference](../reference/api.md) for a markdown rendered API reference.
+
+[openapi_v1]: https://github.com/quay/clair/tree/main/httptransport/api/v1