validate the rest-api

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

.github/workflows/test.yml

@@ -16,6 +16,23 @@ env:
   LANG: C.UTF-8
 
 jobs:
+  rest-api:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+      - name: Validate REST API
+        uses: char0n/swagger-editor-validate@182d1a5d26ff5c2f4f452c43bd55e2c7d8064003
+        with:
+          definition-file: docs/rest-api.yml
+
+      - uses: actions/setup-python@v2
+        with:
+          python-version: "3.9"
+      - run: |
+          pip install -r docs/requirements.txt pytest
+      - run: |
+          pytest docs/
+
   # Run "pytest jupyterhub/tests" in various configurations
   pytest:
     runs-on: ubuntu-20.04

docs/rest-api.yml

@@ -3,7 +3,7 @@ swagger: "2.0"
 info:
   title: JupyterHub
   description: The REST API for JupyterHub
-  version: 1.4.0
+  version: 2.0.0b3
   license:
     name: BSD-3-Clause
 schemes: [http, https]

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,
+    )

jupyterhub/_version.py

@@ -1,13 +1,13 @@
 """JupyterHub version info"""
 # Copyright (c) Jupyter Development Team.
 # Distributed under the terms of the Modified BSD License.
-
 version_info = (
     2,
     0,
     0,
     "b3",  # release (b1, rc1, or "" for final or dev)
     # "dev",  # dev or nothing for beta/rc/stable releases
+    # when updating, make sure to update version in docs/rest-api.yaml as well
 )
 
 # pep 440 version: no dot before beta/rc, but before .dev