I'm using springfox-boot-starter 3.0 to build my API documents.
All things are going in a right way except one case. There seems to be no way to show a JSON example in Swagger UI model if my request parameter is a Map or JSONObject like this:
@PostMapping("/trigger")
@ApiOperation(value = "trigger something")
@ApiImplicitParams(
@ApiImplicitParam(name = "reqForm",
value = "{\"123123\":\"123123\"}", example = "{\"123123\":\"123123\"}"))
public StandardResult trigger(@RequestBody Map reqForm) throws Exception {
Object dagId = reqForm.get("dagId");
Object conf = reqForm.get("conf");
return StandardResult.succeed(dagService.trigger(dagId, conf));
}
I just want to show an example value and a example model of the JSON in Swagger UI and I don't want to write any of extra .java file to define the structure.
Other controllers with plenty of .java files to describe structure can be shown in Swagger UI like this:
But in this case, the Map shall be a dynamic parameter which would change frequently. So I hope to show a model of that JSON without too many .java files so that others who are reading my document would have a nice experience and I will not have to change .java file every day.
I know how to show the model and examples in Swagger UI by creating multiple Java beans using @ApiModel and @ApiModelProperty. But that may also lead to a dozens of .java files in order to create only one JSON and it is hard to find and update a property while something in JSON was changed.
For example, I'm going to tell others to send a JSON like this:
"dagInfo": {
"id": 17,
"tags": [
"test",
"task",
"dag"
],
"interval": "None",
"dagName": "testDagGenerate",
"dagCode": "test_dag_generate",
"dagDescription": "test"
}
by using @ApiImplicitParams shown below, I can show the example value but no model in Swagger UI.
@PostMapping("/trigger")
@ApiOperation(value = "trigger something")
@ApiImplicitParams(
@ApiImplicitParam(name = "reqForm",
value = "example json", example = "\"dagInfo\": {\n" +
" \"id\": 17,\n" +
" \"tags\": [\n" +
" \"test\",\n" +
" \"task\",\n" +
" \"dag\"\n" +
" ],\n" +
" \"interval\": \"None\",\n" +
" \"dagName\": \"testDagGenerate\",\n" +
" \"dagCode\": \"test_dag_generate\",\n" +
" \"dagDescription\": \"test\"\n" +
" }"))
public StandardResult trigger(@RequestBody JSONObject reqForm) throws Exception {
Long dagId = reqForm.getObject("dagId", Long.class);
JSONObject conf = reqForm.getJSONObject("conf");
return StandardResult.succeed(dagService.trigger(dagId, conf));
}
I have no idea how to write this model of example JSON directly to Swagger. Or there is no way to define a example model in Swagger UI without any configuration?
The dependency of Maven is shown below:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>