improve(docker): bail out + provide helpful error if injection fails (via #5007)

* add `onFound` callback to schemas

* add warning to method docs (for #4957)

* implement Docker OAuth2 init block support

* update docs

* add OAUTH_SCOPE_SEPARATOR

* drop OAuth env from Dockerfile and run script

* don't indent the first oauth block line

* drop unused `dedent` import

* touch up warning message

* add more test cases

* return an empty block if no OAuth content is generated

* fix broken doc line

* allow legacy values to override base values

* TEMPORARY (DROP THIS): use legacy HTML from Petstore

* improve(docker): bail out + provide helpful error if injection fails

* Revert "TEMPORARY (DROP THIS): use legacy HTML from Petstore"

This reverts commit 10c18c333262c5411197d9bb085c6b95305beb19.

docker/configurator/index.js

@@ -16,9 +16,28 @@ const startMarkerIndex = originalHtmlContent.indexOf(START_MARKER)
 const endMarkerIndex = originalHtmlContent.indexOf(END_MARKER)
 
 const beforeStartMarkerContent = originalHtmlContent.slice(0, startMarkerIndex)
-const afterEndMarkerContent = originalHtmlContent.slice(endMarkerIndex + END_MARKER.length)
+const afterEndMarkerContent = originalHtmlContent.slice(
+  endMarkerIndex + END_MARKER.length
+)
 
-fs.writeFileSync(targetPath, `${beforeStartMarkerContent}
+if (startMarkerIndex < 0 || endMarkerIndex < 0) {
+  console.error("ERROR: Swagger UI was unable to inject Docker configuration data!")
+  console.error("!      This can happen when you provide custom HTML to Swagger UI.")
+  console.error("!  ")
+  console.error("!      In order to solve this, add the `Begin Swagger UI call region`")
+  console.error("!      and `End Swagger UI call region` markers to your HTML.")
+  console.error("!      See the repository for an example:")
+  console.error("!      https://github.com/swagger-api/swagger-ui/blob/02758b8125dbf38763cfd5d4f91c7c803e9bd0ad/dist/index.html#L40-L54")
+  console.error("!  ")
+  console.error("!      If you're seeing this message and aren't using custom HTML,")
+  console.error("!      this message may be a bug. Please file an issue:")
+  console.error("!      https://github.com/swagger-api/swagger-ui/issues/new/choose")
+  process.exit(0)
+}
+
+fs.writeFileSync(
+  targetPath,
+  `${beforeStartMarkerContent}
       ${START_MARKER}
       const ui = SwaggerUIBundle({
         ${indent(translator(process.env, { injectBaseConfig: true }), 8, 2)}
@@ -26,4 +45,5 @@ fs.writeFileSync(targetPath, `${beforeStartMarkerContent}
       
       ${indent(oauthBlockBuilder(process.env), 6, 2)}
       ${END_MARKER}
-${afterEndMarkerContent}`)
\ No newline at end of file
+${afterEndMarkerContent}`
+)