feat(api): Experiment with auth input visibility on operation pages

EXPERIMENTAL FINDINGS (Task 4):

Tested RapiDoc's allow-authentication attribute with both render-style
options to determine if it can show credential input on operation pages.

Results:
1. render-style='read' + allow-authentication='true':
   - Auth section (#auth) exists in shadow DOM with input fields
   - BUT filtered out by match-paths (not visible to users)
   - Only matched operation shown, not full spec

2. render-style='focused' + allow-authentication='true':
   - Auth section completely removed from shadow DOM
   - Shows broken links to non-existent #auth section
   - Lists security schemes but no input fields

CONCLUSION:
RapiDoc's built-in auth UI is incompatible with match-paths filtering.
When filtering to single operations, the auth section is either hidden
or removed entirely.

RECOMMENDATION:
Implement custom auth input component (Task 5) using:
- Custom TypeScript component above RapiDoc
- sessionStorage for credential persistence
- Integration with RapiDoc's Try it feature

Code includes detailed inline documentation of findings for future
reference when implementing Task 5.

assets/js/components/rapidoc-mini.ts

@@ -34,7 +34,8 @@ interface ThemeConfig {
 
 type CleanupFn = () => void;
 
-// Use full RapiDoc for proper auth tooltip behavior (mini version has limited features)
+// Use full RapiDoc for proper auth tooltip behavior
+// (mini version has limited features)
 const RAPIDOC_CDN = 'https://unpkg.com/rapidoc/dist/rapidoc-min.js';
 const RAPIDOC_ELEMENT = 'rapi-doc';
 
@@ -182,7 +183,38 @@ function createRapiDocElement(
   );
   element.setAttribute('font-size', 'default'); // Match surrounding content size
 
-  // Layout - use 'read' style for proper auth element layout
+  // Layout - use 'read' style for compact, single-operation display
+  //
+  // EXPERIMENTAL FINDINGS (Task 4 - API Security Schemes):
+  // -----------------------------------------------------
+  // RapiDoc's `allow-authentication="true"` DOES NOT show auth input
+  // on operation pages when using `match-paths` to filter to a single
+  // operation. Here's what was tested:
+  //
+  // 1. render-style="read" + allow-authentication="true":
+  //    - Auth section (#auth) exists in shadow DOM with input fields
+  //    - BUT it's not visible (filtered out by match-paths)
+  //    - Only shows the matched operation, not the full spec
+  //    - Found: username/password inputs for Basic auth in shadow DOM
+  //    - Result: NO visible auth UI for users
+  //
+  // 2. render-style="focused" + allow-authentication="true":
+  //    - Auth section completely removed from shadow DOM
+  //    - Shows links to #auth section that don't exist (broken links)
+  //    - Lists security schemes but no input fields
+  //    - Result: NO auth section at all
+  //
+  // CONCLUSION:
+  // RapiDoc's built-in authentication UI is incompatible with
+  // match-paths filtering. The auth section is either hidden or
+  // completely removed when filtering to single operations.
+  // For credential input on operation pages, we need a custom
+  // component (Task 5).
+  //
+  // RECOMMENDATION:
+  // - Keep render-style="read" for compact operation display
+  // - Implement custom auth input component above RapiDoc (Task 5)
+  // - Use sessionStorage to pass credentials to "Try it" feature
   element.setAttribute('layout', 'column');
   element.setAttribute('render-style', 'read');
   element.setAttribute('show-header', 'false');