Fix: Incorrect docs on passing filters in request body (#6124, PR #6136)

lambdas/service/app.py

@@ -1020,16 +1020,23 @@ def repository_search_params_spec():
     ]
 
 
-parameter_hoisting_note = fd('''
-    Any of the query parameters documented below can alternatively be passed as
-    a property of a JSON object in the body of the request. This can be useful
-    in case the value of the `filters` query parameter causes the URL to exceed
-    the maximum length of 8192 characters, resulting in a 413 Request Entity Too
-    Large response.
-
-    The request `GET /index/foo?filters={…}`, for example, is equivalent to a
-    `POST /index/foo` request with the body `{"filters": {…}}`.
-''')
+def parameter_hoisting_note(method: str,
+                            endpoint: str,
+                            equivalent_method: str
+                            ) -> str:
+    return fd('''
+        Any of the query parameters documented below can alternatively be passed
+        as a property of a JSON object in the body of the request. This can be
+        useful in case the value of the `filters` query parameter causes the URL
+        to exceed the maximum length of 8192 characters, resulting in a 413
+        Request Entity Too Large response.
+
+        The request `%s %s?filters={…}`, for example, is equivalent to  `%s %s`
+        with the body `{"filters": "{…}"}` in which any double quotes or
+        backslash characters inside `…` are escaped with another backslash. That
+        escaping is the requisite procedure for embedding one JSON structure
+        inside another.
+    ''' % (method, endpoint, equivalent_method, endpoint))
 
 
 def repository_search_spec(*, post: bool):
@@ -1040,7 +1047,8 @@ def repository_search_spec(*, post: bool):
             {", with filters provided in the request body" if post else ""}.
         '''),
         'deprecated': post,
-        'description': iif(post, parameter_hoisting_note + fd('''
+        'description':
+            iif(post, parameter_hoisting_note('GET', '/index/files', 'POST') + fd('''
 
             Note that the Swagger UI can't currently be used to pass a body.
 
@@ -1311,7 +1319,9 @@ def manifest_route(*, fetch: bool, initiate: bool):
                 Swagger UI. Please use [PUT /fetch/manifest/files][1] instead.
 
                 [1]: #operations-Manifests-put_fetch_manifest_files
-            ''') + parameter_hoisting_note if initiate and not fetch else fd('''
+            ''') + parameter_hoisting_note('PUT', '/manifest/files', 'PUT')
+            if initiate and not fetch else
+            fd('''
                 Check on the status of an ongoing manifest preparation job,
                 returning either
 
@@ -1344,7 +1354,9 @@ def manifest_route(*, fetch: bool, initiate: bool):
                 manifest generation job is done.
 
                 [1]: #operations-Manifests-put_manifest_files
-            ''') + parameter_hoisting_note if initiate and fetch else fd('''
+            ''') + parameter_hoisting_note('PUT', '/fetch/manifest/files', 'PUT')
+            if initiate and fetch else
+            fd('''
                 Check on the status of an ongoing manifest preparation job,
                 returning a 200 status response whose JSON body emulates the
                 HTTP headers that would be found in a response to an equivalent

lambdas/service/openapi.json

@@ -2341,7 +2341,7 @@
             "post": {
                 "summary": "\nSearch an index for entities of interest\n, with filters provided in the request body.\n",
                 "deprecated": true,
-                "description": "\nAny of the query parameters documented below can alternatively be passed as\na property of a JSON object in the body of the request. This can be useful\nin case the value of the `filters` query parameter causes the URL to exceed\nthe maximum length of 8192 characters, resulting in a 413 Request Entity Too\nLarge response.\n\nThe request `GET /index/foo?filters={\u2026}`, for example, is equivalent to a\n`POST /index/foo` request with the body `{\"filters\": {\u2026}}`.\n\n\nNote that the Swagger UI can't currently be used to pass a body.\n\nPlease also note that this endpoint should be considered beta and\nmay change or disappear in the future. That is the reason for the\ndeprecation.\n",
+                "description": "\nAny of the query parameters documented below can alternatively be passed\nas a property of a JSON object in the body of the request. This can be\nuseful in case the value of the `filters` query parameter causes the URL\nto exceed the maximum length of 8192 characters, resulting in a 413\nRequest Entity Too Large response.\n\nThe request `GET /index/files?filters={\u2026}`, for example, is equivalent to  `POST /index/files`\nwith the body `{\"filters\": \"{\u2026}\"}` in which any double quotes or\nbackslash characters inside `\u2026` are escaped with another backslash. That\nescaping is the requisite procedure for embedding one JSON structure\ninside another.\n\n\nNote that the Swagger UI can't currently be used to pass a body.\n\nPlease also note that this endpoint should be considered beta and\nmay change or disappear in the future. That is the reason for the\ndeprecation.\n",
                 "tags": [
                     "Index"
                 ],
@@ -8173,7 +8173,7 @@
                     "Manifests"
                 ],
                 "summary": "Initiate the preparation of a manifest",
-                "description": "\nCreate a manifest preparation job, returning either\n\n- a 301 redirect to the URL of the status of that job or\n\n- a 302 redirect to the URL of an already prepared manifest.\n\nThis endpoint is not suitable for interactive use via the\nSwagger UI. Please use [PUT /fetch/manifest/files][1] instead.\n\n[1]: #operations-Manifests-put_fetch_manifest_files\n\nAny of the query parameters documented below can alternatively be passed as\na property of a JSON object in the body of the request. This can be useful\nin case the value of the `filters` query parameter causes the URL to exceed\nthe maximum length of 8192 characters, resulting in a 413 Request Entity Too\nLarge response.\n\nThe request `GET /index/foo?filters={\u2026}`, for example, is equivalent to a\n`POST /index/foo` request with the body `{\"filters\": {\u2026}}`.\n",
+                "description": "\nCreate a manifest preparation job, returning either\n\n- a 301 redirect to the URL of the status of that job or\n\n- a 302 redirect to the URL of an already prepared manifest.\n\nThis endpoint is not suitable for interactive use via the\nSwagger UI. Please use [PUT /fetch/manifest/files][1] instead.\n\n[1]: #operations-Manifests-put_fetch_manifest_files\n\nAny of the query parameters documented below can alternatively be passed\nas a property of a JSON object in the body of the request. This can be\nuseful in case the value of the `filters` query parameter causes the URL\nto exceed the maximum length of 8192 characters, resulting in a 413\nRequest Entity Too Large response.\n\nThe request `PUT /manifest/files?filters={\u2026}`, for example, is equivalent to  `PUT /manifest/files`\nwith the body `{\"filters\": \"{\u2026}\"}` in which any double quotes or\nbackslash characters inside `\u2026` are escaped with another backslash. That\nescaping is the requisite procedure for embedding one JSON structure\ninside another.\n",
                 "parameters": [
                     {
                         "name": "catalog",
@@ -9581,7 +9581,7 @@
                     "Manifests"
                 ],
                 "summary": "Initiate the preparation of a manifest via XHR",
-                "description": "\nCreate a manifest preparation job, returning a 200 status\nresponse whose JSON body emulates the HTTP headers that would be\nfound in a response to an equivalent request to the [PUT\n/manifest/files][1] endpoint.\n\nWhenever client-side JavaScript code is used in a web\napplication to request the preparation of a manifest from Azul,\nthis endpoint should be used instead of [PUT\n/manifest/files][1]. This way, the client can use XHR to make\nthe request, retaining full control over the handling of\nredirects and enabling the client to bypass certain limitations\non the native handling of redirects in web browsers. For\nexample, most browsers ignore the `Retry-After` header in\nredirect responses, causing them to prematurely exhaust the\nupper limit on the number of consecutive redirects, before the\nmanifest generation job is done.\n\n[1]: #operations-Manifests-put_manifest_files\n\nAny of the query parameters documented below can alternatively be passed as\na property of a JSON object in the body of the request. This can be useful\nin case the value of the `filters` query parameter causes the URL to exceed\nthe maximum length of 8192 characters, resulting in a 413 Request Entity Too\nLarge response.\n\nThe request `GET /index/foo?filters={\u2026}`, for example, is equivalent to a\n`POST /index/foo` request with the body `{\"filters\": {\u2026}}`.\n",
+                "description": "\nCreate a manifest preparation job, returning a 200 status\nresponse whose JSON body emulates the HTTP headers that would be\nfound in a response to an equivalent request to the [PUT\n/manifest/files][1] endpoint.\n\nWhenever client-side JavaScript code is used in a web\napplication to request the preparation of a manifest from Azul,\nthis endpoint should be used instead of [PUT\n/manifest/files][1]. This way, the client can use XHR to make\nthe request, retaining full control over the handling of\nredirects and enabling the client to bypass certain limitations\non the native handling of redirects in web browsers. For\nexample, most browsers ignore the `Retry-After` header in\nredirect responses, causing them to prematurely exhaust the\nupper limit on the number of consecutive redirects, before the\nmanifest generation job is done.\n\n[1]: #operations-Manifests-put_manifest_files\n\nAny of the query parameters documented below can alternatively be passed\nas a property of a JSON object in the body of the request. This can be\nuseful in case the value of the `filters` query parameter causes the URL\nto exceed the maximum length of 8192 characters, resulting in a 413\nRequest Entity Too Large response.\n\nThe request `PUT /fetch/manifest/files?filters={\u2026}`, for example, is equivalent to  `PUT /fetch/manifest/files`\nwith the body `{\"filters\": \"{\u2026}\"}` in which any double quotes or\nbackslash characters inside `\u2026` are escaped with another backslash. That\nescaping is the requisite procedure for embedding one JSON structure\ninside another.\n",
                 "parameters": [
                     {
                         "name": "catalog",