swagger-api / swagger-api/swagger-ui

Swagger-UI has a treacherous hidden dependency on an exposed ObjectMapper object and does not render Request Body if its strategy is set to SNAKE_CASE

Open
#7,806 0 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

Background

In a Java application, we needed an ObjectMapper instance (for something else, completely unrelated to Swagger UI) and by accident, without thinking, we used the following code:

ObjectMapper objectMapper = io.swagger.v3.core.util.Json.mapper()
    .setPropertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE);

And yes, this was not good, we should not have manipulated with this ObjectMapper. But:

Unwanted Behaviour

This causes that the generated api-doc JSON file contains

"request_body": {
    "content": {
        ...
    }
}

instead of

"requestBody": {

The result is that the Swagger-UI does not show the Request Body at all. All the web services appear like without a request body.

This is a treacherous behaviour, quite difficult to debug and discover.

Expected Behaviour

I would expect the following behaviour (both items individually):

  1. Swagger-UI should not expose at all the instance of ObjectMapper it is dependent on, because anyone may break it so Swagger-UI may stop working.

  2. The rendering of Swagger-UI should not be dependent on the PropertyNamingStrategies. Snake case should be as good as Camel case.

Versions
  • io.swagger.core.v3/swagger-project/2.1.12
  • org.webjars/swagger-ui/4.2.1
  • org.springdoc/springdoc-openapi-webflux-ui/1.6.5

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

Reproduce the issue with the shown ObjectMapper SNAKE_CASE setup, then inspect the generated OpenAPI JSON and Swagger UI rendering. Trace where request_body is consumed and how the UI obtains OpenAPI data; done means request bodies render despite the naming strategy and Swagger UI no longer depends on a mutable exposed mapper.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, javascript
Domain
frontend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 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.