Merge pull request treasure-data#1292 from treasure-data/swagger-api-doc

Serve REST API document as a static HTML at docs.digdag.io/api/
st-tech · Dec 24, 2019 · f30dec4 · f30dec4
2 parents 1b23035 + 1c6d715
commit f30dec4
Show file tree

Hide file tree

Showing 6 changed files with 53 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@
 
 Please check [digdag.io](https://digdag.io) and [docs.digdag.io](https://docs.digdag.io) for installation & user manual.
 
-REST API document is available at [swagger.digdag.io](http://swagger.digdag.io/).
+REST API document is available at [docs.digdag.io/api](http://docs.digdag.io/api/).
 
 ## Development
 
@@ -133,7 +133,7 @@ $ npm run dev    # starts dev server on http://localhost:9000/
 
 ### Updating REST API document
 
-Run this command to update REST API document at digdag-docs/src/_static/swagger.yaml.
+Run this command to update REST API document file at digdag-docs/src/api/swagger.yaml.
 
 ```
 ./gradlew swaggerYaml  # dump swagger.yaml file

diff --git a/build.gradle b/build.gradle
@@ -413,7 +413,7 @@ task swaggerYaml(dependsOn: ':digdag-cli:shadowJar') {
         file("config/dummy.properties").write("")
         Process server = ["java", "-jar", "digdag-cli/build/libs/digdag-cli-${project.version}-all.jar", "server", "-c", "config/dummy.properties", "--memory", "--enable-swagger"].execute()
         sleep(5 * 1000)
-        ["curl", "http://127.0.0.1:65432/api/swagger.yaml", "-o", "digdag-docs/src/_static/swagger.yaml"].execute().waitFor()
+        ["curl", "http://127.0.0.1:65432/api/swagger.yaml", "-o", "digdag-docs/src/_extra/api/swagger.yaml"].execute().waitFor()
         server.destroy()
         server.waitForOrKill(1000)
     }

diff --git a/digdag-docs/src/_extra/api/index.html b/digdag-docs/src/_extra/api/index.html
@@ -0,0 +1,48 @@
+<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <script type="module" src="https://unpkg.com/[email protected]/dist/rapidoc-min.js"></script>
+</head>
+<body>
+  <rapi-doc
+    id="rapidoc"
+    spec-url="swagger.yaml"
+    allow-try="false"
+    allow-authentication="false"
+    allow-spec-url-load="false"
+    allow-spec-file-load="false"
+    show-info="false"
+    heading-text="Digdag REST API"
+    header-color="#f0f2f4"
+    regular-font="BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
+  >
+    <div slot="logo" style="height:36px;width:36px;margin-left:5px;margin-right:auto;">
+      <a href="https://digdag.io"><img src="../_static/logo/dig-dag-logo-tr.png" alt="Digdag logo" height="36" width="36" /></img></a>
+    </div>
+  </rapi-doc>
+
+  <script>
+    // Modify style here because RapiDoc doesn't highlight deprecated endpoints.
+    // Deprecated endpoints are highlighted with "read" mode https://github.com/mrin9/RapiDoc/issues/91,
+    // but not with default "view" mode.
+    const markDeprecated = function() {
+      const rapidocRoot = document.querySelector("#rapidoc").shadowRoot  // Shadow DOM is not directly accessible
+      rapidocRoot.querySelectorAll(".m-endpoint").forEach(function(endpointEl) {
+        // Find endpoints whose description is empty (undocumented) or includes /deprecate/i (deprecated).
+        const descText = endpointEl.querySelector(".descr").textContent
+        if (!descText || descText.toLowerCase().includes("deprecate")) {
+          // Mark it as deprecated by changing style
+          endpointEl.querySelector(".method").setAttribute("style", "color:#bbb;border-color:#bbb;")
+          endpointEl.querySelector(".path").setAttribute("style", "color:#bbb;")
+          endpointEl.querySelector(".descr").setAttribute("style", "color:#bbb;")
+        }
+      })
+    }
+    // Use setTimeout instead of spec-loaded event because spec-loaded is not added rapidoc
+    // since 7.0.5 and it is not released yet.
+    //document.getElementById("doc").addEventListener('spec-loaded', markDeprecated)
+    setTimeout(markDeprecated, 500)
+  </script>
+</body>
+</html>
diff --git a/digdag-docs/src/_static/swagger.yaml → digdag-docs/src/_extra/api/swagger.yaml b/digdag-docs/src/_static/swagger.yaml → digdag-docs/src/_extra/api/swagger.yaml
diff --git a/digdag-docs/src/conf.py b/digdag-docs/src/conf.py
@@ -64,6 +64,7 @@ def setup(app):
 # 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 = ['_extra']
 
 html_context = {
   'extra_css_files': ['_static/custom.css']

diff --git a/digdag-docs/src/rest_api.rst b/digdag-docs/src/rest_api.rst
@@ -1,5 +1,5 @@
 REST API
 ==================================
 
-Open API document is available at `swagger.digdag.io <https://swagger.digdag.io/>`_.
+Open API document is available at `docs.digdag.io/api <https://docs.digdag.io/api/>`_.