[Jobs] [Doc] Add Jobs openapi spec and REST API documentation

dashboard/modules/job/job_head.py

@@ -143,7 +143,17 @@ async def close(self, ignore_error=True):
 
 
 class JobHead(dashboard_utils.DashboardHeadModule):
-    """Runs on the head node of a Ray cluster and handles Ray Jobs APIs."""
+    """Runs on the head node of a Ray cluster and handles Ray Jobs APIs.
+
+    NOTE(architkulkarni): Please keep this class in sync with the OpenAPI spec at
+    `doc/source/cluster/running-applications/job-submission/openapi.yml`.
+    We currently do not automatically check that the OpenAPI
+    spec is in sync with the implementation. If any changes are made to the
+    paths in the @route decorators or in the Responses returned by the
+    methods (or any nested fields in the Responses), you will need to find the
+    corresponding field of the OpenAPI yaml file and update it manually, and
+    bump the version number in the yaml file and in this class's `get_version`.
+    """
 
     # Time that we sleep while tailing logs while waiting for
     # the supervisor actor to start. We don't know which node

doc/requirements-doc.txt

@@ -59,6 +59,7 @@ sphinxcontrib.yt==0.2.2
 sphinx-sitemap==2.2.0
 sphinx-thebe==0.1.1
 autodoc_pydantic==1.6.1
+sphinxcontrib-redoc==1.6.0
 
 # MyST
 myst-parser==0.15.2