Swagger UI Middleware Dev Tools

A JS userscript that streamlines working with the Middleware's Swagger UI: it fetches and auto-renews auth tokens for pre-configured users, authorizes both the Bearer and Basic schemes in one click, and removes repetitive friction from the endpoint UI (auto "Try it out", hidden example schemas, live-response-only view).

All authorization is done through Swagger UI's own Redux store, so it stays in sync with the native dialog and keeps working whether the dialog is open or closed. The tool also allows manual operations with Basic and Bearer tokens.

Requirements

• A Chromium-based browser or Firefox.
• Tampermonkey (or a compatible userscript manager such as Violentmonkey).
• Access to a Swagger UI page served from one of the matched hosts (see Matching & permissions).

Setup

First install a userscript manager such as Tampermonkey. Then install the script using one of the methods below.

Install from OpenUserJS (recommended)

One-click install and automatic updates:

Install

Open that URL with the userscript manager installed; it will prompt you to install. Updates are then delivered automatically by your userscript manager.

Install manually

For those who prefer not to use OpenUserJS:

1. Open the Tampermonkey dashboard → Create a new script (or Utilities → Import).
2. Paste the contents of Swagger_UI_Middleware_Dev_Tools.user.js.
3. Save (Ctrl/Cmd + S).

Note: with a manual install you won't get automatic updates; re-paste the latest version to upgrade.

After installing

Chrome (and Chromium-based browsers: Edge, Brave, Opera, Arc...)

1. Click the puzzle-piece Extensions icon in the toolbar and pin Tampermonkey (or your manager) for easy access.
2. Right-click on the Tampermonkey icon, then Manage extension.

   

3. Enable the option Allow User Scripts.

   

Once permissions are set:

1. Open (or reload) a Swagger UI page on a matched host. You should see a small tool icon appear in the Swagger top bar.
2. If not sure, open your browser console once and confirm a line like Swagger UI Middleware Dev Tools v3.1.1 initialised. Enabled: true.

Configure your users

Configuration is done in the app, not by editing the script (so updates never overwrite it). On first run with no saved config, the Configuration dialog opens automatically. You can also open it any time via:

• the tool icon in the Swagger top bar -> Configuration,
• the (Configure) link next to the Pre-configured user label in the auth dialog, or
• the userscript manager's menu -> Configure....

The dialog shows a JSON blob you edit directly:

{
  "users": [
    { "username": "you@example.com", "password": "your-password" }
  ],
  "domains": {
    "TST": "https://authorization.proconnect.tst.publicis.com",
    "DEV": "https://authorization.proconnect.dev.publicis.com",
    "LOCAL": "https://authorization.proconnect.dev.publicis.com"
  },
  "tokenEndpoint": "/api/authorization/users/token",
  "fullTokenTtl": 2700,
  "renewalPostExpiryBufferSecs": 5,
  "showMainPageBanner": false,
  "usersSearchEndpoint": "/api/users/search",
  "customClaimTokenEndpoint": "/api/authorization/users/{referenceIdentityId}/token",
  "customClaim": {
    "application": "string",
    "businessGroups": ["string"],
    "jobFamily": "string",
    "region": "string",
    "client": "string"
  }
}

Replace the dummy user with your own accounts, then Save. The blob is validated live; Save stays disabled until it is valid. Reset to defaults repopulates the editor with the shipped defaults (you still Save to apply). Changes apply immediately, no reload needed.

The environment (TST/DEV/LOCAL) is auto-detected from the page hostname.

Note: users, domains, and tokenEndpoint fully replace the defaults when saved, so if a future update changes a default domain you'll need to update your saved config to pick it up.

⚠️ Credentials & privacy

Your accounts are entered through the in-app Configuration dialog and stored privately in your browser via the userscript manager's storage (GM_setValue). They are not part of the published script, and they survive script updates.

• The published script ships with a dummy user (you@example.com) only, so no real credentials live in the source.
• Stored credentials are visible to anyone with access to your browser profile and are sent to the configured auth server when fetching tokens. Treat them like any saved password.

Matching & permissions

The script runs on hosts declared in its metadata header:

@grant    GM_xmlhttpRequest
@grant    GM_getValue
@grant    GM_setValue
@grant    GM_registerMenuCommand
@match    https://*.publicis.com/*
@match    http://localhost:*/*
@match    http://127.0.0.1:*/*
@connect  authorization.proconnect.tst.publicis.com
@connect  authorization.proconnect.dev.publicis.com
@connect  authorization.proconnect.local.publicis.com

To use it elsewhere, add the appropriate @match (page host) and @connect (auth server host) lines.

Features

• One-click token auth: pick a pre-configured user and fetch a token; both the Bearer and Basic Authentication schemes are authorized at once.

  

• Automatic token renewal: tokens are renewed in the background so long sessions don't 401, including after the tab has been idle.

  

• Token display: the raw Bearer <token> is shown in a read-only field for easy manual copy, and persists when you reopen the dialog.

  

• Token with custom claims: optionally fetch a token enriched with custom claims (application, business groups, job family, region, client); the active claims are shown inline in the authorized status and the token auto-renews on the same path.

  

• Bearer prefill: the native token input is pre-filled with Bearer (cursor at the end) so you can paste a token without typing the prefix.

  

• Auto "Try it out": every operation opens ready to execute; the redundant toggle is hidden, Reset stays available.

  

• Cleaner responses: static example schemas are hidden; after Execute only the live response is shown.

  

• Show/Hide Basic Auth: a link in the auth dialog reveals the Basic Auth section when you need to interact with it manually (only shown when a Basic scheme exists, i.e. authorization service).

  

• Enable/disable toggle: a top-bar icon turns all tweaks on or off; when off, the UI reverts to vanilla Swagger.

  

• In-app configuration: manage your users and environment settings from a validated JSON editor; stored in your browser and preserved across script updates.

  

• Theme-aware: injected UI inherits the page's light/dark colors.

Usage

Authorize

1. Click Authorize in Swagger UI to open the auth dialog.
2. In the Middleware Dev Tools panel, pick a user from Pre-configured user.
3. Click Get token. The panel shows Authorized as <user> - expires at <time>. Auto-renewal active., the token appears in the Token field, and the native Bearer/Basic sections switch to their authorized state.
4. Close the dialog and use the API as usual. Tokens renew automatically in the background.

Switch users

Select a different user and click Get token again - the previous user is logged out first, then the new user is authorized for both schemes.

Get a token with custom claims

1. Open the auth dialog and pick a user.
2. Check with custom claims next to the Get token button. A textarea appears pre-filled with the customClaim from your configuration (or the default shape if not set).
3. Edit the JSON claims as needed. The textarea validates live; Get token stays disabled while the JSON is invalid.
4. Click Get token.

The flow runs in three steps:

1. Fetches a regular bearer token using your credentials (same as the normal flow). Swagger UI is authorized with this token immediately so requests work even if the next steps take a moment.
2. Searches for your user account by username to retrieve the referenceIdentityId.
3. Exchanges the referenceIdentityId and your custom claims body for a claims-enriched token, then overwrites the Swagger Bearer auth with it.

Steps 2 and 3 authenticate with the regular bearer token via the X-Middleware-Authorization header. If either step fails the session stays valid with the regular bearer token, and a message in the status line explains what happened.

While a custom-claims token is active, the authorized line (and the main-page banner, if enabled) shows the claims inline, for example Authorized as you@example.com with custom claims {"application":"mars"} - expires at ... Auto-renewal active.

Auto-renewal follows the same path, re-using the cached referenceIdentityId (so it skips the user search) and re-fetching a fresh custom-claims token; renewal log lines for this path are prefixed with [Custom claims].

On first use the customClaim, usersSearchEndpoint, and customClaimTokenEndpoint values are saved to your stored configuration automatically.

Copy the token manually

The Token field holds Bearer <token>. Click it to select all, then copy. It persists if you close and reopen the dialog while authorized.

Paste a token by hand

The native Bearer Value input is pre-filled with Bearer and the cursor placed at the end, so you can paste just the raw token.

Show the Basic Auth section

Click Show Basic Auth in the dialog header to reveal the Basic Authentication section (hidden by default while the tool is enabled). Click Hide Basic Auth to collapse it again. The link only appears when the spec actually defines a Basic scheme.

Log out

Use the native Logout button in the auth dialog. The tool clears its status, the token display, and the authorized line, and logs out every scheme so the UI and the actual request auth stay consistent.

Edit configuration

Open the Configuration dialog (top-bar icon -> Configuration, the (Configure) link by the user selector, or the userscript-manager menu -> Configure...). Edit the JSON, then Save (enabled only when valid). Use Reset to defaults to start from the shipped config. Saved settings persist across updates.

Turn the tool on/off

Click the tool icon in the Swagger top bar and choose Enable/Disable. When disabled, the icon shows a strike-through and the page reverts to vanilla Swagger UI behavior (no auto try-it-out, no hidden responses, no injected panel). The setting persists across reloads.

How auto-renewal works

The auth server caches one token per user and returns that same token (with its remaining life) until it expires, only minting a fresh one once the old has expired. The script therefore schedules each renewal to fire just after the current token expires (expiresIn + renewalPostExpiryBufferSecs), which reliably yields a fresh full-life token.

There is a brief window - about renewalPostExpiryBufferSecs seconds, once per token lifetime - where the old token has expired and the new one hasn't arrived yet. A request landing exactly there may 401 and succeed on retry. If the tab was backgrounded across the expiry (browsers throttle background timers), returning focus to the tab triggers an immediate renewal.

Troubleshooting

• No tool icon in the top bar: confirm the page host matches a @match rule and that the script is enabled in Tampermonkey. Reload the page.
• 401 right after a long idle period: return focus to the tab; renewal fires on focus. If it persists, re-fetch a token from the dialog.
• 401 on every request: verify the selected environment/domain is correct and the user's credentials are valid.
• Auth dialog looks out of sync: close and reopen it; the tool re-applies the stored authorization on open.

Diagnostics

A console helper is available for debugging Swagger store access:

window.mdtReduxDiagnostic()

It logs which store-resolution strategy works, the detected security schemes, and the current authorized state. The script also logs timestamped [MDT] lines for token fetches and renewals.

Notes & limitations

• All authorization goes through Swagger UI's Redux store via ui.getSystem(); there is no DOM-clicking fallback.
• Theme colors are sampled when the dialog opens; switching the page theme while a dialog is already open won't live-repaint it (reopen to re-sample).
• The script targets the Middleware's Swagger UI; other Swagger setups may use different scheme names or DOM and aren't guaranteed to work without adjustment.