java - 如何在 Swagger UI 中显示自定义 JSON？

Question

我正在使用 springfox-boot-starter 3.0 来构建我的 API 文档。

除了一个案例外，所有事情都在以正确的方式进行。如果我的请求参数是这样的 Map 或 JSONObject ，似乎无法在 Swagger UI 模型中显示 JSON 示例：

    @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));
    }

我只想在 Swagger UI 中显示 JSON 的示例值和示例模型，我不想编写任何额外的 .java 文件来定义结构。

其他具有大量 .java 文件来描述结构的控制器可以在 Swagger UI 中显示，如下所示：

但是在这种情况下，地图应该是一个动态的参数，会经常变化。所以我希望展示一个没有太多 .java 文件的 JSON 模型，以便其他正在阅读我的文档的人会有很好的体验，而我不必每天都更改 .java 文件。

我知道如何通过使用@ApiModeland创建多个 Java bean 在 Swagger UI 中显示模型和示例@ApiModelProperty。但这也可能会导致几十个 .java 文件，以便只创建一个 JSON，并且当 JSON 中的某些内容发生更改时，很难找到和更新属性。

例如，我将告诉其他人发送这样的 JSON：

"dagInfo": {
        "id": 17,
        "tags": [
            "test",
            "task",
            "dag"
        ],
        "interval": "None",
        "dagName": "testDagGenerate",
        "dagCode": "test_dag_generate",
        "dagDescription": "test"
    }

通过使用@ApiImplicitParams如下所示，我可以在 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));
    }

我不知道如何将这种示例 JSON 模型直接写入 Swagger。或者没有任何配置就无法在 Swagger UI 中定义示例模型？

Maven的依赖关系如下图：

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-boot-starter</artifactId>
   <version>3.0.0</version>
</dependency>

标签： javaswagger-uiopenapispringfox