0
  • SpringDoc 1.5.3 (latest)
  • SwaggerUI 3.41.0 (latest)

Swagger UI shows nice fields for @RequestParam.

I have a POST endpoint, so I used @RequestBody.
I can send a JSON and it parses into my body object. So far so good.

But Swagger UI shows only a textarea, where I am supposed to put the whole JSON. Which is not too convenient.

I would like Swagger UI to show individual fields for each property of the request class; and have that without the YAMLs - just with annotations. Although, YAML solution is ok if no other option.

The closest I found is @ParameterObject support for POST, discussed here:

class MyParam (
    val a: String,
    val b: SomeEnum,
    @field:Parameter(required = false)
    val someId: String?,
)

@PostMapping("/...", consumes = [ MediaType.APPLICATION_JSON_VALUE ])
fun addMyEntity(
      @ParameterObject param: MyParam
)

However, this seems to build the object from the query parameters.

In SpringFox, there used to be @ApiModel and @ApiModelParameter, which I suppose would do this. SpringDoc migration page suggests to replace that with @Schema, but I couldn't figure out how.

Is there something that would make Swagger UI to display fields from a class in the same way, but assemble a JSON body from it? And Spring would still parse it from body?

Perhaps something like:

fun addInsisPaymentRequest(
      @BodyObject param: MyParam
)
Ondra Žižka
  • 43,948
  • 41
  • 217
  • 277

1 Answers1

1

I doubt the feasibility of your proposed solution. The reason for it being, the POST/PUT requests accept a request body, which as you're aware can take any valid payload.

The payload can range from primitive types to custom objects used by the application. Also, the data type is not limited to JSON but can be XML, HAL, etc.

Also, a point worth noting is any valid Json/Xml can have recursive objects. Consider the below example.

{
  "prop1": "val1",       // 1st order element
  "prop2": {             // 1st order element
    "sub-prop1": "val2", // 2nd order element
    "sub-prop2": [       // 2nd order element
      "val3",
      "val4"
    ]
  }

Now the question that arises is, you can have a representation similar to we have for query parameter for all of them, but how would you represent the order in which they should appear?

As far as @ParameterObjects are concerned, they are mostly of primitive types. Although it's not impossible to have them as complex types, I don't think a lot of us do it often.

Debargha Roy
  • 2,320
  • 1
  • 15
  • 34
  • It should be feasible: `application/x-www-form-urlencoded` is roughly the same format as what the query part of URL contains. So I see no problem taking that and parsing it the very same way, except from the body. Which parser is used is given by the content type, how is the resulting data (list, map, tree) interpreted is up to the unmarshaler. So why not have an unmarshaller for this. – Ondra Žižka Feb 11 '21 at 07:03