⬆️ upgrade swagger-ui to 5.27.1 by josemigallas · Pull Request #4218 · 3scale/porta

josemigallas · 2026-02-05T14:54:16Z

THREESCALE-12255: Update swagger-ui to 5.27.1

Latest is 5.31 but 5.28 breaks our implementation. While I figure out why, this is the most recent version we can update to.

Verification steps

This module is used in OAS 3 specs in the following pages:

3scale API Documentation /p/admin/api_docs
api_docs with apiconfig/services/:service_id/api_docs/:id/preview
dev portal docs page /docs

ℹ️ https://github.com/swagger-api/swagger-ui/releases

qltysh · 2026-02-05T14:55:47Z

❌ 17 blocking issues (24 total)

Tool	Category	Rule	Count
eslint	Lint	Unsafe member access .catch on an `any` value.	6	❌
eslint	Lint	Unsafe argument of type `any` assigned to a parameter of type `SchemaProperty`.	3	❌
eslint	Lint	Unsafe call of an `any` typed value.	2	❌
eslint	Lint	Unsafe spread of an `any` value in an array.	2	❌
eslint	Lint	Unsafe return of an `any` typed value.	2	❌
eslint	Lint	Variable name `ClearDefaultValuesPlugin` must match one of the following formats: camelCase, UPPER_CASE	1	❌
eslint	Lint	This assertion is unnecessary since it does not change the type of the expression.	1	❌
qlty	Structure	Function with high complexity (count = 10): clearGeneratedDefaults	5
qlty	Structure	Function with many returns (count = 7): ClearDefaultValuesPlugin	2

jlledom

What's the problem with 5.28? It's surprising we can upgrade 2 major versions at once but then there's a breaking change in a minor version.

jlledom

Seems to work fine for me, I found a small bug. In the request body section for POST and PUT requests, the fields are auto-filled wrongly, I think.

Before:

After:

mayorova · 2026-02-09T09:54:07Z

Seems to work fine for me, I found a small bug. In the request body section for POST and PUT requests, the fields are auto-filled wrongly, I think.

That rings a bell... See Notes for reviewer in #3934

josemigallas · 2026-02-09T11:30:18Z

What's the problem with 5.28? It's surprising we can upgrade 2 major versions at once but then there's a breaking change in a minor version.

It's TBI (to be investigated). It simply throws an error in the browser console and doesn't render anything.

github-actions · 2026-04-16T04:33:11Z

This PR is stale because it has not received activity for more than 30 days. Remove stale label or comment or this will be closed in 15 days.

jlledom · 2026-04-17T12:43:58Z

I've been checking this. I rebased to master and tried to update to 5.32.4, the last release.

I hit the error after upgrading to 5.28.0. After an investigation I found the problem is due to 5.28.0 and later versions depending on React 18 de facto: even when their package.json states they accept React between 16 and 19, the fact is they only accept React 18 and 19 by mistake. People depending on swagger-ui-dist receive the correct React already bundled, but we use swagger-ui which expects React to be installed by us.

Somebody hit the same bug: swagger-api/swagger-ui#10636

And there's a fix already, but not merged: swagger-api/swagger-ui#10642

The fix looks abandoned, it doesn't seem it's going to be merged soon. So we can't rely on that. In order to upgrade to newer versions, we would need:

react: 17.0.2 → 18.3.1
react-dom: 17.0.2 → 18.3.1
react-redux: 7.2.9 → ^9.2.0
@wojtekmaj/enzyme-adapter-react-17 → @cfaester/enzyme-adapter-react-18
Add resolutions for swagger-ui/react and swagger-ui/react-dom → 18.3.1
Fix tests

I told Claude to do it and I could upgrade to swagger-ui 5.32.4. Everything in porta looked correct. So it can be done. I kept the branch if you are interested.

IMO we should merge this and get swagger-ui 5.27.1. In another PR we can upgrade to React 18 and last swagger-ui release. The issue I mentioned in this comment would still need to be fixed: #4218 (review)

jlledom · 2026-04-29T08:42:34Z

I took this issue while @josemigallas is out. I made some changes and this is the current status:

swagger-ui upgraded to 5.27.1, we can't go further without upgrading to React 18
swagger-ui pulls minimatch@^10.0.0 which includes a license change. The new license, BlueOak-1.0.0 is approved by OSI and Fedora. I added it to the list of permitted licenses: 4c52779
Newer versions of swagger-ui set a default value for fields in POST and PUT requests, like 0 for numbers or "string" for strings. I was discussing with Claude how to do fix this, considering I know very little about TypeScript or swagger-ui particularities. Finally I opted for writing a plugin that overwrites those default values: 0b22dbb

mayorova · 2026-05-08T12:26:27Z

  }
 }

+const ClearDefaultValuesPlugin: SwaggerUIPlugin = () => {


This plugin seems to be working well for our own API docs (/p/admin/api_docs), but it is not applied to the preview of the API docs in admin portal, and the published versions in the dev portal :(

Honestly, this feature is so weird, it's extremely annoying to have to remove this pre-filled "example" values!!!

Right! Here: 48f45bf

Do you think it would be possible to also apply this logic when "Reset" is clicked?...

Screencast.From.2026-05-18.13-11-07.mp4

I did it: 24cd50d

I was annoying Claude until the code was fast enough, however, the resulting code is pretty complicated.

OMG... This code is something... and might be a potential ticking bomb for the next Swagger UI upgrade, maybe?...

Why do we need to upgrade swagger-ui again? 😅

Co-Authored-By: Claude <noreply@anthropic.com>

Newer swagger-ui versions auto-fill form fields with generated defaults like "string" for string types or 0 for integers. This was not the previous behavior, where fields were left empty with the parameter name shown as an HTML placeholder. Add ClearDefaultValuesPlugin which wraps the JsonSchemaForm component and sets dispatchInitialValue to false, preventing the auto-fill on initial render. The plugin is extracted into its own module and applied across all three API docs screens: provider admin, per-service, and developer portal. Co-Authored-By: Claude <noreply@anthropic.com>

akostadinov · 2026-05-18T17:54:37Z

@jlledom , great work, glad you decided to adopt this one!

Could you review the qlty (eslint) report and see what makes sense and what doesn't?

Also Bob suggested a new plugin test:

// test/javascript/src/ActiveDocs/ClearDefaultValuesPlugin.spec.ts              
describe('ClearDefaultValuesPlugin', () => {                                    
  it('prevents initial default value dispatch', () => {                         
    // Test that dispatchInitialValue is set to false                           
  });                                                                           
                                                                                
  it('maintains behavior after reset', () => {                                  
    // Test reset button interaction                                            
  });                                                                           
});

Replace the fn.getSampleSchema override with two targeted overrides to eliminate per-keystroke overhead. The previous implementation wrapped getSampleSchema which was called ~20 times per keystroke as swagger-ui recomputes initialValue on every render. New approach combines: - JsonSchemaForm wrapper that sets dispatchInitialValue=false for primitive fields without explicit examples/defaults (handles initial render) - selectDefaultRequestBodyValue selector wrapper that clears generated defaults from the Reset button value (handles form reset) Neither fires per keystroke since JsonSchemaForm runs at mount and the selector is only called by onResetClick. Assisted-by: Claude Code

Add comprehensive test coverage for the optimized plugin including: - JsonSchemaForm wrapper behavior with Immutable.js schema objects - Conditional dispatchInitialValue based on schema examples/defaults - selectDefaultRequestBodyValue selector wrapper - clearGeneratedDefaults helper function Tests verify that generated defaults ("string", 0, true) are cleared while explicit examples and defaults from the spec are preserved. Assisted-by: Claude Code

Add Cucumber feature tests that verify the ClearDefaultValuesPlugin behavior in the browser using the Swagger UI interface. Tests cover both initial form field values and Reset button behavior. The feature ensures that form fields for properties without explicit examples/defaults remain empty while fields with explicit values show those values correctly. Includes a new test fixture (user-api-3.0.json) and supporting step definitions for checking request body field values. Assisted-by: Claude Code

Remove unused JsonSchemaFormProperties import from ThreeScaleApiDocs.ts since it's no longer referenced in the file.

Add comprehensive inline documentation to clarify the plugin's two-override strategy and implementation details for code reviewers. Comments explain: - The purpose of each interface, constant, and helper function - The distinction between plain-object and Immutable.js schema handling - Why each override runs when it does (mount vs Reset) - Content-type filtering rationale (form-encoded vs JSON) - The wrapSelectors calling convention and parameter usage This makes the optimization approach more understandable without requiring knowledge of previous implementation attempts or swagger-ui internals. Assisted-by: Claude Code

jlledom · 2026-05-19T16:08:11Z

Also Bob suggested a new plugin test:

Here: 78dc76b

And here: 2b9107c

jlledom · 2026-05-19T16:34:42Z

Could you review the qlty (eslint) report and see what makes sense and what doesn't?

I don't think any of those is worth the time.

josemigallas requested a review from a team February 6, 2026 10:13

josemigallas self-assigned this Feb 6, 2026

jlledom reviewed Feb 9, 2026

View reviewed changes

github-actions Bot added the Stale label Mar 14, 2026

3scale deleted a comment from github-actions Bot Mar 16, 2026

josemigallas removed the Stale label Mar 16, 2026

github-actions Bot added the Stale label Apr 16, 2026

jlledom removed the Stale label Apr 16, 2026

jlledom force-pushed the THREESCALE-12255_swagger_ui_27 branch from 9f1e455 to 276e4e4 Compare April 28, 2026 15:14

jlledom requested review from akostadinov and mayorova April 29, 2026 08:30

jlledom force-pushed the THREESCALE-12255_swagger_ui_27 branch from ec96dc5 to 4c52779 Compare April 29, 2026 08:44

mayorova reviewed May 8, 2026

View reviewed changes

josemigallas and others added 7 commits May 18, 2026 09:56

⬆️ upgrade swagger-ui to 5.27.1

82e8d7e

New yarn.lock after rebasing onto master

abb0aad

Bump swagger-ui to 5.34.2

c803dcb

Set version to 5.27.1

cbf4534

Add swagger-ui plugin to delete placeholders

358545d

Co-Authored-By: Claude <noreply@anthropic.com>

Add BlueOak to the list of permitted licenses

6f3cfda

jlledom force-pushed the THREESCALE-12255_swagger_ui_27 branch from 48f45bf to 9d01a34 Compare May 18, 2026 08:30

jlledom requested a review from mayorova May 18, 2026 08:39

jlledom added 5 commits May 19, 2026 17:57

refactor(active-docs): remove unused import

69c0c4d

Remove unused JsonSchemaFormProperties import from ThreeScaleApiDocs.ts since it's no longer referenced in the file.

Conversation

josemigallas commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Verification steps

Uh oh!

qltysh Bot commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❌ 17 blocking issues (24 total)

Uh oh!

jlledom left a comment

Choose a reason for hiding this comment

Uh oh!

jlledom left a comment

Choose a reason for hiding this comment

Uh oh!

mayorova commented Feb 9, 2026

Uh oh!

josemigallas commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Apr 16, 2026

Uh oh!

jlledom commented Apr 17, 2026

Uh oh!

jlledom commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mayorova May 8, 2026

Choose a reason for hiding this comment

Uh oh!

jlledom May 11, 2026

Choose a reason for hiding this comment

Uh oh!

mayorova May 18, 2026

Choose a reason for hiding this comment

Uh oh!

jlledom May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mayorova May 19, 2026

Choose a reason for hiding this comment

Uh oh!

akostadinov commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jlledom commented May 19, 2026

Uh oh!

jlledom commented May 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

josemigallas commented Feb 5, 2026 •

edited

Loading

qltysh Bot commented Feb 5, 2026 •

edited

Loading

josemigallas commented Feb 9, 2026 •

edited

Loading

jlledom commented Apr 29, 2026 •

edited

Loading

jlledom May 19, 2026 •

edited

Loading

akostadinov commented May 18, 2026 •

edited

Loading