swagger-api / swagger-api/swagger-ui

springdoc-openapi v2(swagger) request object query encoding issue

Open
#10,113 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

After migrating from springdoc-openapi v1 to v2, we started experiencing issues with requests using a query param DTO.
Previously, requests were structured as standard query parameters, but now they are being URL-encoded, leading to errors.

Here is an example of a swagger request object query:

{
  "searchType": "ACCOUNT_ID",
  "searchKeywords": [
    "12345"
  ],
  "types": [
    "NORMAL",
    "WITHDRAW"
  ]
}

With springdoc-openapi v1, the request URL looked like this:

http://localhost:8080/search?searchType=ACCOUNT_ID&searchKeywords=12345&types=NORMAL&types=WITHDRAW

However, after upgrading to springdoc-openapi v2, the request URL changed to the following (with the query parameters URL-encoded):

http://localhost:8080/search?searchType=ACCOUNT_ID&searchKeywords=%5B%2212345%22%5D&types=%5B%22NORMAL%22%2C%22WITHDRAW%22%5D

Decoded, it looks like:

http://localhost:8080/search?searchType=ACCOUNT_ID&searchKeywords=["12345"]&types=["NORMAL","WITHDRAW"]

Although the requests work fine when using curl, it seems to be an issue with the new version of springdoc-openapi v2(swagger).
It doesn't appear to be a application problem.

How should we address this?

I am using org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the request in Swagger UI with the provided query DTO and comparing its generated URL with the springdoc-openapi v1 and v2 examples. Trace the query-parameter serialization path; done means array values are sent as standard repeated query parameters rather than JSON-encoded arrays, while preserving the curl-compatible behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, openapi, spring
Domain
api, frontend
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.