Automate loading of AMS and Gateway API spec from swagger

.gitignore

@@ -14,3 +14,5 @@ __pycache__
 .vscode/
 .sphinx/styles/*
 .sphinx/vale.ini
+.sphinx/deps/
+.sphinx/_static/swagger-ui/

.sphinx/_extra/ams-api.yaml

@@ -0,0 +1 @@
+../../reference/api-reference/ams-api.yaml

.sphinx/_extra/gateway-api.yaml

@@ -0,0 +1 @@
+../../reference/api-reference/gateway-api.yaml

custom_conf.py

@@ -1,4 +1,7 @@
 import datetime
+import os
+import subprocess
+
 
 # Custom configuration for the Sphinx documentation builder.
 # All configuration specific to your project should be done in this file.
@@ -213,6 +216,7 @@
 rst_prolog = """
 .. role:: center
    :class: align-center
+
 """
 
 
@@ -227,3 +231,32 @@ def generate_ams_configuration():
             custom_required_modules.append(req)
     ams_configuration_file = "reference/ams-configuration.md"
     parse_swagger(get_swagger_from_url(), ams_configuration_file)
+
+## The following code is to automatically load the API from swagger into documentation.
+
+# Path to copy the YAML files during build
+html_extra_path = ['.sphinx/_extra']
+
+# The swagger-ui repository is required to be able to render the swagger YAML
+# file as browseable API documentation. The below variables specify which
+# git repository to fetch it from and the revision in that repository to use.
+# This will be helpful to protect against the documentation breaking due to
+# backwards-incompatible changes in the swagger-ui repository. However, this
+# means that updating to newer revisions of this repository needs to be done
+# manually.
+swagger_ui_repository = "https://github.com/swagger-api/swagger-ui"
+swagger_ui_revision = "d1111837388816f0b68f27a1a0d6a6f37841b697"
+
+# Download and link swagger-ui files
+if not os.path.isdir('.sphinx/deps/swagger-ui'):
+    subprocess.check_call(["git", "clone", swagger_ui_repository, "./sphinx/deps/swagger-ui"])
+    subprocess.check_call(["git", "reset", "--hard", swagger_ui_revision])
+
+os.makedirs('.sphinx/_static/swagger-ui/', exist_ok=True)
+
+if not os.path.islink('.sphinx/_static/swagger-ui/swagger-ui-bundle.js'):
+    os.symlink('../../deps/swagger-ui/dist/swagger-ui-bundle.js', '.sphinx/_static/swagger-ui/swagger-ui-bundle.js')
+if not os.path.islink('.sphinx/_static/swagger-ui/swagger-ui-standalone-preset.js'):
+    os.symlink('../../deps/swagger-ui/dist/swagger-ui-standalone-preset.js', '.sphinx/_static/swagger-ui/swagger-ui-standalone-preset.js')
+if not os.path.islink('.sphinx/_static/swagger-ui/swagger-ui.css'):
+    os.symlink('../../deps/swagger-ui/dist/swagger-ui.css', '.sphinx/_static/swagger-ui/swagger-ui.css')

reference/api-reference/ams-api.md

@@ -0,0 +1,29 @@
+# Main API specification
+
+<link rel="stylesheet" type="text/css" href="../../../_static/swagger-ui/swagger-ui.css" ></link>
+<link rel="stylesheet" type="text/css" href="../../../_static/swagger-override.css" ></link>
+<div id="swagger-ui"></div>
+
+<script src="../../../_static/swagger-ui/swagger-ui-bundle.js" charset="UTF-8"> </script>
+<script src="../../../_static/swagger-ui/swagger-ui-standalone-preset.js" charset="UTF-8"> </script>
+<script>
+window.onload = function() {
+  // Begin Swagger UI call region
+  const ui = SwaggerUIBundle({
+    url: window.location.pathname +"../../../ams-api.yaml",
+    dom_id: '#swagger-ui',
+    deepLinking: true,
+    presets: [
+      SwaggerUIBundle.presets.apis,
+      SwaggerUIStandalonePreset
+    ],
+    plugins: [],
+    validatorUrl: "none",
+    defaultModelsExpandDepth: -1,
+    supportedSubmitMethods: []
+  })
+  // End Swagger UI call region
+
+  window.ui = ui
+}
+</script>