opencadc · pdowler · May 6, 2026 · Jul 15, 2024 · Sep 3, 2024 · Sep 5, 2024
diff --git a/youcat/build.gradle b/youcat/build.gradle
@@ -15,9 +15,9 @@ sourceCompatibility = 11
 group = 'ca.nrc.cadc'
 
 war {
-    // Include the swagger-ui so that /cat provides the cat API documentation
+    // Include the swagger UI so that base URL provides API docs
     from(System.getenv('RPS') + '/resources/') {                
-        include 'swagger-ui/'                      
+        include 'swagger-openapi/dist/'                      
     }                                                                
 }
 

diff --git a/youcat/openapi-linter b/youcat/openapi-linter
@@ -0,0 +1,10 @@
+#!/bin/bash
+
+test -d src/main/webapp && cd src/main/webapp
+
+if [[ "$1" == "-it" ]]; then
+  docker run -it --rm -v $PWD:/work:ro dshanley/vacuum /bin/bash
+else
+  docker run --rm -v $PWD:/work:ro dshanley/vacuum lint --no-clip -d openapi.yaml
+fi
+
diff --git a/youcat/rsync-openapi-components.sh b/youcat/rsync-openapi-components.sh
@@ -0,0 +1,14 @@
+#!/bin/bash
+
+VOSI=$HOME/work/dev/ivoa-std/VOSI.git
+DALI=$HOME/work/dev/ivoa-std/DALI.git
+TAP=$HOME/work/dev/ivoa-std/TAP.git
+
+ARGS="$1 -avc --delete"
+
+rsync $ARGS $VOSI/openapi/vosi src/main/webapp/openapi/
+rsync $ARGS $VOSI/openapi/uws src/main/webapp/openapi/
+
+rsync $ARGS $DALI/openapi/dali src/main/webapp/openapi/
+rsync $ARGS $TAP/openapi/tap src/main/webapp/openapi/
+
diff --git a/youcat/src/main/java/org/opencadc/youcat/YoucatInitAction.java b/youcat/src/main/java/org/opencadc/youcat/YoucatInitAction.java
@@ -81,6 +81,10 @@
 import ca.nrc.cadc.uws.server.impl.InitDatabaseUWS;
 import ca.nrc.cadc.vosi.actions.DeleteAction;
 import ca.nrc.cadc.vosi.actions.TablesAction;
+import java.net.URL;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.StandardCopyOption;
 import javax.naming.Context;
 import javax.naming.InitialContext;
 import javax.security.auth.Subject;
@@ -107,6 +111,8 @@ public class YoucatInitAction extends InitAction {
     private Boolean createSchemaInDB = false;
     private String defaultVOTableSerialization = null;
     private String deletedSchemaName = null;
+
+    private boolean adminConfigured = false;
     private String metadataValidation = null;
 
     public YoucatInitAction() { 
@@ -127,10 +133,12 @@ private void initConfig() {
         sb.append("\n\t").append(YOUCAT_ADMIN).append(": ");
         if (adminUserStr == null) {
             sb.append("MISSING");
+            this.adminConfigured = false;
         } else {
             try {
                 IdentityManager im = AuthenticationUtil.getIdentityManager();
                 admin = im.toSubject(adminUserStr);
+                this.adminConfigured = true;
                 String str = admin.toString().replaceAll("\n", " ");
                 sb.append(str).append(" OK");
             } catch (Exception ex) {
@@ -236,6 +244,25 @@ public void doInit() {
             DeleteAction.setDeletedSchemaName(deletedSchemaName);
 
             TablesAction.setValidatorConfig(prepareValidatorConfig(metadataValidation));
+            initOpenApiDocs();
+        } catch (Exception ex) {
+            throw new RuntimeException("INIT FAIL: " + ex.getMessage(), ex);
+        }
+    }
+
+    private void initOpenApiDocs() {
+        try {
+            URL resURL = super.getResource("openapi-base.yaml");
+            if (adminConfigured) {
+                resURL = super.getResource("openapi-youcat.yaml");
+            }
+
+            String path = resURL.getPath();
+            log.debug("found openapi: " + resURL + " at " + path);
+            Path src = Path.of(resURL.toURI());
+            Path dest = src.getParent().resolve("openapi.yaml");
+            Files.copy(src, dest, StandardCopyOption.COPY_ATTRIBUTES);
+            log.info("api docs: " + src + " -> " + dest);
         } catch (Exception ex) {
             throw new RuntimeException("INIT FAIL: " + ex.getMessage(), ex);
         }

diff --git a/youcat/src/main/webapp/index.html b/youcat/src/main/webapp/index.html
@@ -1,165 +1,85 @@
 <!DOCTYPE html>
-<html>
+<html lang="en">
 <head>
-  <meta charset="UTF-8">
-  <title>youcat API</title>
-  <link rel="icon" type="image/png"
-        href="swagger-ui/images/favicon-32x32.png" sizes="32x32"/>
-  <link rel="icon" type="image/png"
-        href="swagger-ui/images/favicon-16x16.png" sizes="16x16"/>
-  <link href='swagger-ui/css/typography.css' media='screen'
-        rel='stylesheet' type='text/css'/>
-  <link href='swagger-ui/css/reset.css' media='screen' rel='stylesheet'
-        type='text/css'/>
-  <link href='swagger-ui/css/screen.css' media='screen' rel='stylesheet'
-        type='text/css'/>
-  <link href='swagger-ui/css/reset.css' media='print' rel='stylesheet'
-        type='text/css'/>
-  <link href='swagger-ui/css/print.css' media='print' rel='stylesheet'
-        type='text/css'/>
-  <script src='swagger-ui/lib/jquery-1.8.0.min.js'
-          type='text/javascript'></script>
-  <script src='swagger-ui/lib/jquery.slideto.min.js'
-          type='text/javascript'></script>
-  <script src='swagger-ui/lib/jquery.wiggle.min.js'
-          type='text/javascript'></script>
-  <script src='swagger-ui/lib/jquery.ba-bbq.min.js'
-          type='text/javascript'></script>
-  <script src='swagger-ui/lib/handlebars-2.0.0.js'
-          type='text/javascript'></script>
-  <script src='swagger-ui/lib/js-yaml.min.js'
-          type='text/javascript'></script>
-  <script src='swagger-ui/lib/lodash.min.js'
-          type='text/javascript'></script>
-  <script src='swagger-ui/lib/backbone-min.js'
-          type='text/javascript'></script>
-  <script src='swagger-ui/swagger-ui.js'
-          type='text/javascript'></script>
-  <script src='swagger-ui/lib/highlight.9.1.0.pack.js'
-          type='text/javascript'></script>
-  <script src='swagger-ui/lib/highlight.9.1.0.pack_extended.js'
-          type='text/javascript'></script>
-  <script src='swagger-ui/lib/jsoneditor.min.js'
-          type='text/javascript'></script>
-  <script src='swagger-ui/lib/marked.js'
-          type='text/javascript'></script>
-  <script src='swagger-ui/lib/swagger-oauth.js'
-          type='text/javascript'></script>
-
-  <style type="text/css">
+    <meta charset="UTF-8">
+    <link rel="icon" type="image/png" href="swagger-openapi/dist/favicon-32x32.png" sizes="32x32"/> 
+    <link rel="icon" type="image/png" href="swagger-openapi/dist/favicon-16x16.png" sizes="16x16"/>
+    <link href='swagger-openapi/dist/index.css' rel='stylesheet' type='text/css'/>
+    <link href='swagger-openapi/dist/swagger-ui.css'rel='stylesheet' type='text/css'/>
+    <title>YouCat API</title>
+    <style>
     /*
     Custom CSS from CADC.
     jenkinsd 2016.03.01
     */
     .swagger-section #header {
       background-color: rgba(42, 125, 166, 0.7);
+      padding: 14px;
     }
 
     .swagger-section #header #logo {
       padding: 0;
+      color: white;
+      font-size: 1.5em;
+      font-weight: bold;
+      text-decoration: none;
     }
 
-    .swagger-section #header a#logo {
-      background: transparent;
+    .swagger-section .swagger-ui,
+    .swagger-section .swagger-ui-wrap {
+      max-width: 960px;
+      margin-left: auto;
+      margin-right: auto;
+      line-height: 1;
+      font-family: "Droid Sans", sans-serif;
     }
-  </style>
-
-  <script type="text/javascript">
-    $(function ()
-      {
-        var url = "service.json";
-
-        hljs.configure({
-                         highlightSizeThreshold: 5000
-                       });
-
-        // Pre load translate...
-        if (window.SwaggerTranslator)
-        {
-          window.SwaggerTranslator.translate();
-        }
-        window.swaggerUi = new SwaggerUi({
-          url: url,
-          dom_id: "swagger-ui-container",
-          supportedSubmitMethods: ['get'],
-          onComplete: function (swaggerApi, swaggerUi)
-          {
-            if (typeof initOAuth == "function")
-            {
-              initOAuth({
-                          clientId: "your-client-id",
-                          clientSecret: "your-client-secret-if-required",
-                          realm: "your-realms",
-                          appName: "your-app-name",
-                          scopeSeparator: ",",
-                          additionalQueryStringParams: {}
-                        });
-            }
-
-            if (window.SwaggerTranslator)
-            {
-              window.SwaggerTranslator.translate();
-            }
-
-            // addApiKeyAuthorization();
-          },
-          onFailure: function (data)
-          {
-            log("Unable to Load SwaggerUI");
-          },
-          docExpansion: "list",
-          jsonEditor: false,
-          apisSorter: "alpha",
-          defaultModelRendering: 'schema',
-          showRequestHeaders: true,
-          validatorUrl: null
-        });
-
-        function addApiKeyAuthorization()
-        {
-          var key = encodeURIComponent($('#input_apiKey')[0].value);
-          if (key && key.trim() != "")
-          {
-            var apiKeyAuth = new SwaggerClient.ApiKeyAuthorization("api_key", key, "query");
-            window.swaggerUi.api.clientAuthorizations.add("api_key", apiKeyAuth);
-            log("added key " + key);
-          }
-        }
 
-        $('#input_apiKey').change(addApiKeyAuthorization);
-
-        // if you have an apiKey you would like to pre-populate on the page for demonstration purposes...
-        /*
-         var apiKey = "myApiKeyXXXX123456789";
-         $('#input_apiKey').val(apiKey);
-         */
+    .swagger-ui .wrapper,
+    .swagger-ui .opblock-tag {
+      padding: 10;
+    }
 
-        window.swaggerUi.load();
+    .swagger-ui .info .title {
+      font-size: 25px;
+      font-weight: bold;
+      color: black;
+    }
 
-        function log()
-        {
-          if ('console' in window)
-          {
-            console.log.apply(console, arguments);
-          }
-        }
-      });
-  </script>
+    .topbar,
+    .swagger-ui .info span,
+    .swagger-ui .info .version,
+    .swagger-ui .scheme-container {
+      display: none !important;
+      height: 0;
+      margin: 0;
+      padding: 0;
+      overflow: hidden;
+    }
+  </style>
 </head>
 
-<body class="swagger-section">
-<div id='header'>
-  <div class="swagger-ui-wrap">
-    <a id="logo" href="${request.servletPath}">youcat API</a>
-    <!-- <form id='api_selector'>
-      <div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div>
-      <div class='input'><input placeholder="api_key" id="input_apiKey" name="apiKey" type="text"/></div>
-      <div class='input'><a id="explore" href="#" data-sw-translate>Explore</a></div>
-    </form> -->
-  </div>
-</div>
-
-<div id="message-bar" class="swagger-ui-wrap" data-sw-translate>&nbsp;</div>
-<div id="swagger-ui-container" class="swagger-ui-wrap"></div>
+<body>
+    <div id="swagger-ui"></div>
+        <script src='swagger-openapi/dist/swagger-ui-bundle.js' type='text/javascript'></script>
+        <script src='swagger-openapi/dist/swagger-ui-standalone-preset.js' type='text/javascript'></script>
+
+        <script>
+            window.onload = () => {
+                window.ui = SwaggerUIBundle({
+                    url: "openapi.yaml",
+                    dom_id: "#swagger-ui",
+                    deepLinking: true,
+                    validatorUrl: "none",
+                    presets: [
+                        SwaggerUIBundle.presets.apis,
+                        SwaggerUIStandalonePreset
+                    ],
+                    plugins: [
+                      SwaggerUIBundle.plugins.DownloadUrl
+                    ],
+                    layout: "StandaloneLayout"
+                });
+            };
+        </script>
 </body>
 </html>
diff --git a/youcat/src/main/webapp/openapi-base.yaml b/youcat/src/main/webapp/openapi-base.yaml
@@ -0,0 +1,41 @@
+openapi: 3.1.0
+info:
+  title: |
+    TAP: generic OpenCADC TAP service implementation
+  version: "0.9.4"
+  description: |
+    This service implements the WD-TAP-1.2 API specification with components imported from
+    VOSI, UWS, and DALI. Querying is completely compatible with the IVOA TAP-1.1 Recommendation.
+
+    This service is configured for basic TAP operation only. While the service implements
+    the complete standard, the UWS job child paths described below are a subset.
+
+servers:
+- url: /youcat
+
+tags:
+    - name: TAP Query
+    - name: VOSI Capabilities
+    - name: VOSI Table Metadata
+
+paths:
+    /sync:
+        $ref: ./openapi/tap/tap-sync.yaml
+    /async:
+        $ref: ./openapi/tap/tap-async.yaml
+    /async/{jobID}:
+        $ref: ./openapi/tap/tap-async-job.yaml
+    /async/{jobID}/phase:
+        $ref: ./openapi/tap/tap-async-job-phase.yaml
+    /async/{jobID}/results/result:
+        $ref: ./openapi/tap/tap-result.yaml
+
+    /capabilities:
+        $ref: ./openapi/vosi/vosi-capabilities.yaml
+
+    /tables:
+        $ref: ./openapi/vosi/vosi-tableset.yaml
+    /tables/{name}:
+        $ref: ./openapi/vosi/vosi-table-11.yaml
+
+