validate the rest-api

both with github action that runs openapi validation,
and a couple local tests to verify some maintenance tasks are done

docs/test_docs.py

@@ -0,0 +1,39 @@
+import sys
+from pathlib import Path
+from subprocess import run
+
+from ruamel.yaml import YAML
+
+yaml = YAML(typ="safe")
+
+here = Path(__file__).absolute().parent
+root = here.parent
+
+
+def test_rest_api_version():
+    version_py = root.joinpath("jupyterhub", "_version.py")
+    rest_api_yaml = root.joinpath("docs", "rest-api.yml")
+    ns = {}
+    with version_py.open() as f:
+        exec(f.read(), {}, ns)
+    jupyterhub_version = ns["__version__"]
+
+    with rest_api_yaml.open() as f:
+        rest_api = yaml.load(f)
+        rest_api_version = rest_api["info"]["version"]
+
+    assert jupyterhub_version == rest_api_version
+
+
+def test_restapi_scopes():
+    run([sys.executable, "source/rbac/generate-scope-table.py"], cwd=here, check=True)
+    run(
+        ['pre-commit', 'run', 'prettier', '--files', 'rest-api.yml'],
+        cwd=here,
+        check=False,
+    )
+    run(
+        ["git", "diff", "--exit-code", str(here.joinpath("rest-api.yml"))],
+        cwd=here,
+        check=True,
+    )