Swagger UI Parameter Rendering Issues: Why Your Enum Values Don't Appear as Dropdowns

Apr 27, 2026

Problem

You’ve configured allowableValues in Swagger annotations, swagger.json shows correct enum values, but Swagger UI displays a plain text input instead of a dropdown.

swagger.json: "enum": ["pos", "wifi", "country"]
Swagger UI: [plain text input field]
Expected: [dropdown with pos, wifi, country options]

Environment

Spring Boot with JAX-RS
swagger-core 1.5.20 or 1.6.2
Swagger UI (version unknown - bundled with framework)
Tested in Firefox and Chrome

What happened?

I configured my Swagger annotations correctly:

@ApiImplicitParam(
    name = "status",
    value = "Filter by status",
    allowableValues = "active, inactive, pending",
    dataType = "string",
    paramType = "query"
)

I verified swagger.json:

{
    "name": "status",
    "in": "query",
    "type": "string",
    "enum": ["active", "inactive", "pending"]
}

Everything looks correct. But Swagger UI still shows a plain text field.

I tried:

Upgrading swagger-core to 1.6.2
Switching to @ApiParam instead of @ApiImplicitParam
Testing in different browsers
Manually adding a schema element to swagger.json

None of these worked.

Why this is confusing

The core issue is that swagger-core and Swagger UI are separate components:

┌─────────────────┐          ┌─────────────────┐
│  swagger-core   │─────────▶│  swagger.json   │
│  (annotations)  │  generates│  (enum exists)  │
└─────────────────┘          └─────────────────┘
                                      │
                                      ▼
                             ┌─────────────────┐
                             │   Swagger UI    │
                             │  (renders spec) │
                             └─────────────────┘

Upgrading swagger-core only affects spec generation. Swagger UI is often bundled separately by your framework (Spring Boot, etc.).

Diagnostic Steps

To find the root cause, check these:

1. Verify Swagger UI Version

Open browser dev tools. Check:

JavaScript console for version info
HTML footer or loaded scripts
Network tab for swagger-ui JS files

// Look for version in loaded UI scripts
// Older versions may not render enums for query params

2. Confirm swagger.json is Loading

Use Network tab to verify:

swagger.json URL is being fetched
Response contains the enum values
No older cached version is being used

3. Clear Browser Cache

Hard refresh:

Windows: Ctrl+Shift+R
Mac: Cmd+Shift+R

4. Check OpenAPI Format

OpenAPI 2.0 and 3.0 use different parameter structures:

{
    "name": "status",
    "in": "query",
    "type": "string",
    "enum": ["active", "inactive"]
}

{
    "name": "status",
    "in": "query",
    "schema": {
        "type": "string",
        "enum": ["active", "inactive"]
    }
}

Swagger UI 3.x+ expects OpenAPI 3.0 format with schema wrapper.

5. Test Standalone Swagger UI

Download swagger-ui-dist and serve your swagger.json directly:

npm install swagger-ui-dist
# Copy your swagger.json to dist folder
# Open index.html and point it to your swagger.json

This isolates UI from framework integration issues.

Potential Solutions

Option 1: Use springdoc-openapi

For Spring Boot, use springdoc-openapi instead of older swagger libraries:

&lt;dependency&gt;
    &lt;groupId&gt;org.springdoc&lt;/groupId&gt;
    &lt;artifactId&gt;springdoc-openapi-ui&lt;/artifactId&gt;
    &lt;version&gt;1.7.0&lt;/version&gt;
&lt;/dependency&gt;

This generates OpenAPI 3.0 format and bundles compatible Swagger UI.

Option 2: Manual Schema Modification

If you can modify swagger.json output, wrap enum in schema:

{
    "name": "status",
    "in": "query",
    "schema": {
        "type": "string",
        "enum": ["active", "inactive", "pending"]
    }
}

Option 3: Upgrade Bundled Swagger UI

If your framework bundles Swagger UI, check if you can override the version.

Option 4: Accept Text Input

Sometimes the practical solution is to document allowed values in the value or description field:

@ApiImplicitParam(
    name = "status",
    value = "Filter by status. Allowed values: active, inactive, pending",
    dataType = "string",
    paramType = "query"
)

Summary

In this post, I explained why Swagger UI may not render enum dropdowns even with correct swagger.json. The key point is that spec generation (swagger-core) and UI rendering (Swagger UI) are separate. Focus troubleshooting on the UI layer: check version, clear cache, test standalone, or migrate to springdoc-openapi for better compatibility.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Stack Overflow: Swagger UI doesn't render allowableValues
👨‍💻 Swagger UI Documentation
👨‍💻 OpenAPI Specification

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!