rules_openapi: add rule to build HTML doc (#4338)

Add openapi_build_doc rule to build the API documentation as
zero-dependency HTML file.
This replaces separate genrules in the build files for the individual
tools. These had all been using the `redoc-cli` command which is
deprecated (in favor of redocly/cli) and had been creating broken HTML
files since #4323.

Fix the link in the dummy index.html page from the private/mgmtapi
package, used when not bundling the generated documentation page, to
point to openapi.json (not spec.json).

Drop the yarn dependency on `redoc-cli` and update all dependencies.

control/mgmtapi/BUILD.bazel

@@ -1,17 +1,10 @@
 load("//tools/lint:go.bzl", "go_library", "go_test")
-load("@com_github_scionproto_scion//rules_openapi:defs.bzl", "openapi_generate_go")
+load("@com_github_scionproto_scion//rules_openapi:defs.bzl", "openapi_build_docs", "openapi_generate_go")
 
-genrule(
-    name = "bundle",
-    srcs = ["//spec:control"],
-    outs = ["index.html"],
-    cmd = (
-        "$(execpath @rules_openapi_npm//redoc-cli/bin:redoc-cli) " +
-        "bundle $(location //spec:control) " +
-        "-o $@"
-    ),
-    tools = ["@rules_openapi_npm//redoc-cli/bin:redoc-cli"],
-    visibility = ["//visibility:public"],
+openapi_build_docs(
+    name = "doc",
+    src = "//spec:control",
+    out = "index.html",
 )
 
 openapi_generate_go(
@@ -30,7 +23,7 @@ go_library(
         ":api_generated",  # keep
     ],
     embedsrcs = select({
-        "//:mgmtapi_bundle_doc_build": [":bundle"],
+        "//:mgmtapi_bundle_doc_build": [":doc"],
         "//conditions:default": [":dummy.html"],
     }),  # keep
     importpath = "github.com/scionproto/scion/control/mgmtapi",

control/mgmtapi/spec.go

@@ -47,5 +47,5 @@ func ServeSpecInteractive(w http.ResponseWriter, r *http.Request) {
 
 // ServeSpecJSON serves the json encoded OpenAPI3 spec.
 func ServeSpecJSON(w http.ResponseWriter, r *http.Request) {
-	http.ServeContent(w, r, "spec.json", modtime, bytes.NewReader(spec))
+	http.ServeContent(w, r, "openapi.json", modtime, bytes.NewReader(spec))
 }

daemon/mgmtapi/BUILD.bazel

@@ -1,17 +1,10 @@
 load("//tools/lint:go.bzl", "go_library")
-load("@com_github_scionproto_scion//rules_openapi:defs.bzl", "openapi_generate_go")
+load("@com_github_scionproto_scion//rules_openapi:defs.bzl", "openapi_build_docs", "openapi_generate_go")
 
-genrule(
-    name = "bundle",
-    srcs = ["//spec:daemon"],
-    outs = ["index.html"],
-    cmd = (
-        "$(execpath @rules_openapi_npm//redoc-cli/bin:redoc-cli) " +
-        "bundle $(location //spec:daemon) " +
-        "-o $@"
-    ),
-    tools = ["@rules_openapi_npm//redoc-cli/bin:redoc-cli"],
-    visibility = ["//visibility:public"],
+openapi_build_docs(
+    name = "doc",
+    src = "//spec:daemon",
+    out = "index.html",
 )
 
 openapi_generate_go(
@@ -30,7 +23,7 @@ go_library(
         ":api_generated",  # keep
     ],
     embedsrcs = select({
-        "//:mgmtapi_bundle_doc_build": [":bundle"],
+        "//:mgmtapi_bundle_doc_build": [":doc"],
         "//conditions:default": [":dummy.html"],
     }),  # keep
     importpath = "github.com/scionproto/scion/daemon/mgmtapi",

daemon/mgmtapi/spec.go

@@ -47,5 +47,5 @@ func ServeSpecInteractive(w http.ResponseWriter, r *http.Request) {
 
 // ServeSpecJSON serves the json encoded OpenAPI3 spec.
 func ServeSpecJSON(w http.ResponseWriter, r *http.Request) {
-	http.ServeContent(w, r, "spec.json", modtime, bytes.NewReader(spec))
+	http.ServeContent(w, r, "openapi.json", modtime, bytes.NewReader(spec))
 }

dispatcher/mgmtapi/BUILD.bazel

@@ -1,17 +1,10 @@
 load("//tools/lint:go.bzl", "go_library")
-load("//rules_openapi:defs.bzl", "openapi_generate_go")
+load("//rules_openapi:defs.bzl", "openapi_build_docs", "openapi_generate_go")
 
-genrule(
-    name = "bundle",
-    srcs = ["//spec:dispatcher"],
-    outs = ["index.html"],
-    cmd = (
-        "$(execpath @rules_openapi_npm//redoc-cli/bin:redoc-cli) " +
-        "bundle $(location //spec:dispatcher) " +
-        "-o $@"
-    ),
-    tools = ["@rules_openapi_npm//redoc-cli/bin:redoc-cli"],
-    visibility = ["//visibility:public"],
+openapi_build_docs(
+    name = "doc",
+    src = "//spec:dispatcher",
+    out = "index.html",
 )
 
 openapi_generate_go(
@@ -30,7 +23,7 @@ go_library(
         ":api_generated",  # keep
     ],
     embedsrcs = select({
-        "//:mgmtapi_bundle_doc_build": [":bundle"],
+        "//:mgmtapi_bundle_doc_build": [":doc"],
         "//conditions:default": [":dummy.html"],
     }),  # keep
     importpath = "github.com/scionproto/scion/dispatcher/mgmtapi",

dispatcher/mgmtapi/spec.go

@@ -47,5 +47,5 @@ func ServeSpecInteractive(w http.ResponseWriter, r *http.Request) {
 
 // ServeSpecJSON serves the json encoded OpenAPI3 spec.
 func ServeSpecJSON(w http.ResponseWriter, r *http.Request) {
-	http.ServeContent(w, r, "spec.json", modtime, bytes.NewReader(spec))
+	http.ServeContent(w, r, "openapi.json", modtime, bytes.NewReader(spec))
 }

gateway/mgmtapi/BUILD.bazel

@@ -1,17 +1,10 @@
 load("//tools/lint:go.bzl", "go_library")
-load("@com_github_scionproto_scion//rules_openapi:defs.bzl", "openapi_generate_go")
+load("@com_github_scionproto_scion//rules_openapi:defs.bzl", "openapi_build_docs", "openapi_generate_go")
 
-genrule(
-    name = "bundle",
-    srcs = ["//spec:gateway"],
-    outs = ["index.html"],
-    cmd = (
-        "$(execpath @rules_openapi_npm//redoc-cli/bin:redoc-cli) " +
-        "bundle $(location //spec:gateway) " +
-        "-o $@"
-    ),
-    tools = ["@rules_openapi_npm//redoc-cli/bin:redoc-cli"],
-    visibility = ["//visibility:public"],
+openapi_build_docs(
+    name = "doc",
+    src = "//spec:gateway",
+    out = "index.html",
 )
 
 openapi_generate_go(
@@ -30,7 +23,7 @@ go_library(
         ":api_generated",  # keep
     ],
     embedsrcs = select({
-        "//:mgmtapi_bundle_doc_build": [":bundle"],
+        "//:mgmtapi_bundle_doc_build": [":doc"],
         "//conditions:default": [":dummy.html"],
     }),  # keep
     importpath = "github.com/scionproto/scion/gateway/mgmtapi",

gateway/mgmtapi/spec.go

@@ -47,5 +47,5 @@ func ServeSpecInteractive(w http.ResponseWriter, r *http.Request) {
 
 // ServeSpecJSON serves the json encoded OpenAPI3 spec.
 func ServeSpecJSON(w http.ResponseWriter, r *http.Request) {
-	http.ServeContent(w, r, "spec.json", modtime, bytes.NewReader(spec))
+	http.ServeContent(w, r, "openapi.json", modtime, bytes.NewReader(spec))
 }

private/mgmtapi/index.html

@@ -6,7 +6,7 @@ <h1>Service Management UI not bundled</h1>
 
     The service management UI is not bundled in this binary.
 
-    The OpenAPI spec is available at <a href="./spec.json">/spec.json</a>
+    The OpenAPI spec is available at <a href="./openapi.json">/openapi.json</a>
 
 </body>
 

router/mgmtapi/BUILD.bazel

@@ -1,17 +1,10 @@
 load("//tools/lint:go.bzl", "go_library", "go_test")
-load("@com_github_scionproto_scion//rules_openapi:defs.bzl", "openapi_generate_go")
+load("@com_github_scionproto_scion//rules_openapi:defs.bzl", "openapi_build_docs", "openapi_generate_go")
 
-genrule(
-    name = "bundle",
-    srcs = ["//spec:router"],
-    outs = ["index.html"],
-    cmd = (
-        "$(execpath @rules_openapi_npm//redoc-cli/bin:redoc-cli) " +
-        "bundle $(location //spec:router) " +
-        "-o $@"
-    ),
-    tools = ["@rules_openapi_npm//redoc-cli/bin:redoc-cli"],
-    visibility = ["//visibility:public"],
+openapi_build_docs(
+    name = "doc",
+    src = "//spec:router",
+    out = "index.html",
 )
 
 openapi_generate_go(
@@ -30,7 +23,7 @@ go_library(
         ":api_generated",  # keep
     ],
     embedsrcs = select({
-        "//:mgmtapi_bundle_doc_build": [":bundle"],
+        "//:mgmtapi_bundle_doc_build": [":doc"],
         "//conditions:default": [":dummy.html"],
     }),  # keep
     importpath = "github.com/scionproto/scion/router/mgmtapi",

router/mgmtapi/spec.go

@@ -47,5 +47,5 @@ func ServeSpecInteractive(w http.ResponseWriter, r *http.Request) {
 
 // ServeSpecJSON serves the json encoded OpenAPI3 spec.
 func ServeSpecJSON(w http.ResponseWriter, r *http.Request) {
-	http.ServeContent(w, r, "spec.json", modtime, bytes.NewReader(spec))
+	http.ServeContent(w, r, "openapi.json", modtime, bytes.NewReader(spec))
 }

rules_openapi/defs.bzl

@@ -1,5 +1,6 @@
 load("//rules_openapi/internal:generate.bzl", _openapi_generate_go = "openapi_generate_go")
 load("//rules_openapi/internal:bundle.bzl", _openapi_bundle = "openapi_bundle")
+load("//rules_openapi/internal:docs.bzl", _openapi_build_docs = "openapi_build_docs")
 load("//rules_openapi/internal:header.bzl", _header = "header")
 load("@cgrindel_bazel_starlib//updatesrc:defs.bzl", "updatesrc_update")
 
@@ -52,3 +53,15 @@ def openapi_generate_go(
         srcs = srcs,
         outs = [":" + name],
     )
+
+def openapi_build_docs(
+        name,
+        src,
+        out,
+        **kwargs):
+    _openapi_build_docs(
+        name = name,
+        src = src,
+        out = out,
+        **kwargs
+    )

rules_openapi/internal/BUILD.bazel

@@ -6,6 +6,7 @@ bzl_library(
     name = "rules_openapi_internal",
     srcs = [
         "bundle.bzl",
+        "docs.bzl",
         "generate.bzl",
         "header.bzl",
     ],

rules_openapi/internal/docs.bzl

@@ -0,0 +1,39 @@
+load("@bazel_skylib//lib:shell.bzl", "shell")
+
+def _openapi_build_docs_impl(ctx):
+    cmd = "{bin} build-docs --output {out} {src}".format(
+        bin = ctx.executable._openapi_cli.path,
+        out = shell.quote(ctx.outputs.out.path),
+        src = shell.quote(ctx.file.src.path),
+    )
+
+    ctx.actions.run_shell(
+        outputs = [ctx.outputs.out],
+        inputs = [ctx.file.src],
+        tools = [ctx.executable._openapi_cli],
+        command = cmd,
+        mnemonic = "OpenAPIBuildDocs",
+        use_default_shell_env = True,
+    )
+    return [DefaultInfo(
+        files = depset([ctx.outputs.out]),
+    )]
+
+openapi_build_docs = rule(
+    implementation = _openapi_build_docs_impl,
+    doc = "This rule can be used to create API documentation as a single, zero-dependency HTML file.",
+    attrs = {
+        "src": attr.label(
+            doc = "The API definition file",
+            allow_single_file = [".yml"],
+        ),
+        "out": attr.output(
+            doc = "The output HTML file generated by this rule",
+        ),
+        "_openapi_cli": attr.label(
+            default = "@rules_openapi_npm//@redocly/cli/bin:openapi",
+            executable = True,
+            cfg = "target",
+        ),
+    },
+)

rules_openapi/tools/package.json

@@ -3,7 +3,6 @@
         "@redocly/cli": "^1.0.0-beta.123",
         "@stoplight/spectral-cli": "^6.6.0",
         "lodash.get": "^4.4.2",
-        "lodash.set": "^4.3.2",
-        "redoc-cli": "^0.13.2"
+        "lodash.set": "^4.3.2"
     }
 }