How to Configure allowableValues in Swagger Annotations for Spring Boot REST APIs

Apr 27, 2026

Purpose

This post demonstrates how to configure allowed parameter values using Swagger annotations in Spring Boot REST APIs, so that swagger.json contains proper enum specifications.

Environment

Spring Boot with JAX-RS
Maven project
swagger-core 1.6.2
swagger-annotations 1.6.2

The Annotations

Swagger provides two annotations for specifying allowed parameter values:

@ApiImplicitParam - for parameters not directly in method signature
@ApiParam - for method parameters

Both support the allowableValues property.

Using @ApiImplicitParam

When your parameter is implicit (like @QueryParam handled by JAX-RS), use @ApiImplicitParam:

@GET
@Path("/locations")
@ApiOperation("Get locations by type")
@ApiImplicitParams({
    @ApiImplicitParam(
        name = "poi_types",
        value = "Types of locations to include",
        allowableValues = "pos, wifi, country",
        dataType = "string",
        paramType = "query"
    )
})
public Response getLocations(@QueryParam("poi_types") String poiTypes) {
    // implementation
}

Key properties:

name - parameter name matching your @QueryParam
value - description for documentation
allowableValues - comma-separated list of allowed values
dataType - typically “string”
paramType - “query” for query parameters

Using @ApiParam

When your parameter is directly in the method signature, use @ApiParam:

@GET
@Path("/countries")
public Response getCountries(
    @QueryParam("isocc2")
    @ApiParam(
        name = "isocc2",
        value = "Country code",
        allowableValues = "en, es, us, cn"
    )
    String countryCode) {
    // implementation
}

Maven Dependencies

Add these to your pom.xml:

&lt;dependency&gt;
    &lt;groupId&gt;io.swagger&lt;/groupId&gt;
    &lt;artifactId&gt;swagger-core&lt;/artifactId&gt;
    &lt;version&gt;1.6.2&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
    &lt;groupId&gt;io.swagger&lt;/groupId&gt;
    &lt;artifactId&gt;swagger-annotations&lt;/artifactId&gt;
    &lt;version&gt;1.6.2&lt;/version&gt;
&lt;/dependency&gt;

Verifying the Output

After configuring annotations, check the generated swagger.json:

{
    "name": "poi_types",
    "in": "query",
    "description": "Types of locations to include",
    "required": false,
    "type": "string",
    "enum": ["pos", "wifi", "country"]
}

The enum array should contain your specified values.

How to Verify

Start your application
Access swagger.json endpoint (usually /swagger.json or /v2/api-docs)
Search for your parameter in the JSON
Confirm the enum array matches your allowableValues

If the enum array is correct, your annotation configuration is working.

Common Issues

Values not appearing in swagger.json - Check annotation syntax and ensure swagger-core is configured to scan your resources.
Swagger UI not showing dropdown - This is a UI rendering issue, not configuration. See related troubleshooting posts.
Multiple parameters - Use @ApiImplicitParams wrapper for multiple @ApiImplicitParam annotations.

Summary

In this post, I showed how to configure allowableValues in Swagger annotations. The key point is using comma-separated values in @ApiImplicitParam or @ApiParam annotations. After configuration, verify swagger.json contains the expected enum array.

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 Core Annotations Documentation

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