Document special requirements for requesting /manifest/files endpoint

amarjandu commented 3 years ago

When requesting manifests from the /manifest/files endpoint users must wait for the generation of the manifests to complete. Currently if a user follows the links provided from the Swagger-UI page under Responses their clients might preemptively report a problem with the endpoint.

Browser:

Curl:

We should have additional documentation within the description that indicates how to use the endpoint.

theathorn commented 3 years ago

@amarjandu What are the "special requirements" (add to Description)?

melainalegaspi commented 3 years ago

@amarjandu to fill in the description.

amarjandu commented 3 years ago

Note: we can also modify the curl commands that are show within the UI.

Something like this might work, although the patch needs some more tweaking.

Index: lambdas/service/vendor/static/swagger-ui.html.template.mustache
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/lambdas/service/vendor/static/swagger-ui.html.template.mustache b/lambdas/service/vendor/static/swagger-ui.html.template.mustache
--- a/lambdas/service/vendor/static/swagger-ui.html.template.mustache   (revision c26641fffbec9c3c2775e32e7050a6c888899422)
+++ b/lambdas/service/vendor/static/swagger-ui.html.template.mustache   (date 1628646480797)
@@ -33,6 +33,14 @@
     <script>
     window.onload = function() {
       // Begin Swagger UI call region
+      ManifestRequestInterceptor = function(request){
+       if (request.url.includes('/manifest/')){
+           request.curlOptions = ['-L', '--max-retries -1', '--retry-delay 0']
+           return request
+       }
+       return request
+     }
       const ui = SwaggerUIBundle({
         url: "/openapi",
         dom_id: '#swagger-ui',
@@ -43,7 +51,9 @@
         plugins: [
           SwaggerUIBundle.plugins.DownloadUrl
         ],
-        oauth2RedirectUrl: {{{OAUTH2_REDIRECT_URL}}}
+        requestInterceptor: ManifestRequestInterceptor,
+        oauth2RedirectUrl: {{{OAUTH2_REDIRECT_URL}}},
+        showMutatedRequest: true
       })
       const client_id = {{{OAUTH2_CLIENT_ID}}};
       if (client_id !== null) {

see: https://github.com/swagger-api/swagger-ui/pull/3534 https://github.com/swagger-api/swagger-ui/commit/cbe99c8c1a6f55a5ed384ce27376ee46d735b48c

amarjandu commented 3 years ago

from standup, we should note early within the description that most user agents DO NOT respect the Retry-After headers.

amarjandu commented 2 years ago

Index: lambdas/service/vendor/resources/static/swagger-ui.html.template.mustache
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/lambdas/service/vendor/resources/static/swagger-ui.html.template.mustache b/lambdas/service/vendor/resources/static/swagger-ui.html.template.mustache
--- a/lambdas/service/vendor/resources/static/swagger-ui.html.template.mustache (revision c34f340ed9ba4678695f209e89268f02902546cf)
+++ b/lambdas/service/vendor/resources/static/swagger-ui.html.template.mustache (date 1645640384061)
@@ -28,8 +28,8 @@

   <body>
     <div id="swagger-ui"></div>
-    <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.24.2/swagger-ui-bundle.js" integrity="sha384-QstYUwgBn9pKkNBAW6ecO40vdhKY2eWzcUnjVXcBxl16Ks0GIgc4k+6EMXI462tG" crossorigin="anonymous"></script>
-    <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.24.2/swagger-ui-standalone-preset.js" integrity="sha384-sTb47WR//agLnr7p+2eMNLxtfLZFYwBzMyh4U/NMCrBeDjPe6leIOcU+7IgdvnBt" crossorigin="anonymous"></script>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.52.4/swagger-ui-bundle.js" integrity="sha512-rhKyOL5hIVzdZHCrRe614JvR5fNohEMmXFsnAgrR13s7VhB7c+yJKiCurnoJJJh0/onsbJox1wYyEh3HYmPh8Q==" crossorigin="anonymous"></script>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.52.4/swagger-ui-standalone-preset.js" integrity="sha512-Pg9Z5NaKZIJmfONs0DZ87NmObgZZKJi0c1y6i5BWn83BCI/cr5QNqxOkrb1mUh23OXKauX8wRjFNtdgt1QB7MQ==" crossorigin="anonymous"></script>
     <script>
     window.onload = function() {
       // Begin Swagger UI call region
@@ -43,7 +43,17 @@
         plugins: [
           SwaggerUIBundle.plugins.DownloadUrl
         ],
-        oauth2RedirectUrl: {{{OAUTH2_REDIRECT_URL}}}
+        oauth2RedirectUrl: {{{OAUTH2_REDIRECT_URL}}},
+        requestInterceptor: (req) => {
+          if (req.url.includes("manifest/")){
+           req.curlOptions = ["-L", "--max-retries -1", "--retry-delay 0"];
+            return req;
+       }
+          else {
+              return req;
+          }
+     },
+        showMutatedRequest: true
       })
       const client_id = {{{OAUTH2_CLIENT_ID}}};
       if (client_id !== null) {

Need to update swagger-ui release version for requestInterceptor support, however this changes breaks the UI.

hannes-ucsc commented 2 years ago

req.curlOptions = ["-L", "--max-retries -1", "--retry-delay 0"];

Please explain the motivation behind this. --max-retries isn't documented for my relatively new version of curl from Dec 2020. And --retry-delay 0 is the default according to the manual.

Aside from that, this ticket is a documentation update. The above comment outlines a change in functionality.

DataBiosphere / azul

Document special requirements for requesting /manifest/files endpoint #3172