docs: bundle external OpenAPI spec visualizer (#1780)

lablup · Dec 12, 2023 · cb46cd8 · cb46cd8
1 parent e9480e4
commit cb46cd8
Show file tree

Hide file tree

Showing 8 changed files with 1,858 additions and 13 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -126,6 +126,12 @@ Example:
 
 Please ask the docs maintainer for help.
 
+### Previewing built HTML documentation
+Simply create a nginx server which serves `_build/html` folder. For example (docker required): 
+```bash
+docker run --rm -it -v $(pwd)/_build/html:/usr/share/nginx/html -p 8000:80 nginx
+```
+Executing the command above inside `docs` folder will serve the documentation page on port 8000 (http://localhost:8000).
 
 ## References for newcomers
 

diff --git a/docs/_static/js/spec-viewer.js b/docs/_static/js/spec-viewer.js
diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html
@@ -1,4 +1,8 @@
-{% extends "!layout.html" %}
-{% block extrahead %}
-<link href="{{ pathto("_static/custom.css", True) }}" rel="stylesheet" type="text/css">
-{% endblock %}
+{%- if meta is mapping and meta.get("render_mode") == "raw" %}
+    {% block body %}{% endblock %}
+{%- else %}
+    {% extends "!layout.html" %}
+    {% block extrahead %}
+    <link href="{{ pathto("_static/custom.css", True) }}" rel="stylesheet" type="text/css">
+    {% endblock %}
+{%- endif %}
diff --git a/docs/conf.py b/docs/conf.py
@@ -44,7 +44,6 @@
     "sphinx_rtd_theme",
     "sphinxcontrib_trio",
     "sphinxcontrib.mermaid",
-    "sphinxcontrib.openapi",
     "sphinx_autodoc_typehints",
 ]
 
@@ -151,6 +150,7 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
+html_extra_path = ["manager/rest-reference/openapi.json"]
 
 # Custom sidebar templates, maps document names to template names.
 # html_sidebars = {}

diff --git a/docs/manager/index.rst b/docs/manager/index.rst
@@ -7,4 +7,4 @@ Backend.AI Manager Reference
    common-api/index
    user-api/intro
    admin-api/intro
-   rest-reference/index
+   rest-reference/index
diff --git a/docs/manager/rest-reference/index.rst b/docs/manager/rest-reference/index.rst
@@ -1,3 +1,18 @@
+:render_mode: raw
+
 Backend.AI REST API Reference
-=====
-.. openapi:httpdomain:: openapi.json
+=============================
+
+.. raw:: html
+
+    <redoc spec-url="../../openapi.json"></redoc>
+    <script src="../../_static/js/spec-viewer.js"> </script>
+    <style>
+      body {
+        margin: 0;
+        padding: 0;
+      }
+      body > section > h1 {
+        display: none;
+      }
+    </style>
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -4,7 +4,6 @@ sphinx-autodoc-typehints~=1.24.0
 sphinx-intl>=2.1
 sphinx-rtd-theme~=1.3
 sphinxcontrib-mermaid~=0.7.1
-sphinxcontrib-openapi~=0.8.1
 rtds-action~=1.1.0
 pygments~=2.16.1
 # replace the following line with native support of Sphinx in Pants

diff --git a/src/ai/backend/manager/openapi.py b/src/ai/backend/manager/openapi.py
@@ -59,7 +59,7 @@ def _traverse(scheme: t.Trafaret) -> dict:
             x for x in trafarets if not (isinstance(x, t.Null) or isinstance(x, UndefChecker))
         ]
         if len(valid_trafarets) >= 2:
-            return {"oneOf": list(_traverse(s) for s in valid_trafarets)}
+            return {"anyOf": list(_traverse(s) for s in valid_trafarets)}
         else:
             scheme = valid_trafarets[0]
     if isinstance(scheme, t.Any):
@@ -122,7 +122,7 @@ def _traverse(scheme: t.Trafaret) -> dict:
         return {"type": "string", "pattern": str(scheme._rx_slug.pattern)}
     if isinstance(scheme, tx.TimeDuration):
         return {
-            "oneOf": [
+            "anyOf": [
                 {
                     "type": "string",
                     "description": (
@@ -195,7 +195,7 @@ def parse_trafaret_definition(root: t.Dict) -> list[dict]:
 
 def generate_openapi(subapps: list[web.Application], verbose=False) -> dict[str, Any]:
     openapi: dict[str, Any] = {
-        "openapi": "3.0.0",
+        "openapi": "3.1.0",
         "info": {
             "title": "Backend.AI Manager API",
             "description": "Backend.AI Manager REST API specification",
@@ -357,11 +357,12 @@ def generate_openapi(subapps: list[web.Application], verbose=False) -> dict[str,
                 openapi["components"]["schemas"][schema_name] = response_schema
                 route_def["responses"] = {
                     "200": {
+                        "description": "",
                         "content": {
                             "application/json": {
                                 "schema": {"$ref": f"#/components/schemas/{schema_name}"}
                             }
-                        }
+                        },
                     }
                 }
             openapi["paths"][path][method.lower()] = route_def