Springdoc 随机 api-docs 生成

Question

我希望生成一个采用不同内容类型的 api。

我面临的问题是，如果我多次运行我的应用程序，我会得到不同的输出文档

@RestController
public class MyRestController {

    @Operation(summary = "GetMyData", operationId = "gettt",
        responses = @ApiResponse(responseCode = "204", content = @Content(mediaType = "application/vnd.something")))
    @GetMapping(produces = "application/vnd.something")
    public ResponseEntity<Void> getSomethingElse() {
        return noContent().build();
    }

    @GetMapping(produces = TEXT_PLAIN_VALUE)
    public String get() {
        return "some text";
    }

    @GetMapping(produces = HAL_JSON_VALUE)
    public EntityModel<JsonResponse> getHal() {
        return EntityModel.of(new JsonResponse(),
            linkTo(MyRestController.class).slash("somelink").withSelfRel()
        );
    }

    @GetMapping(produces = APPLICATION_JSON_VALUE)
    public JsonResponse getJson() {
        return new JsonResponse();
    }
}

它当前生成错误的 api-docs

"operationId": "gettt_1_1_1",
"responses": {
    "200": {
        "content": {
            "application/hal+json": {
                "schema": {
                    "$ref": "#/components/schemas/EntityModelJsonResponse"
                }
            },
            "application/json": {
                "schema": {
                    "$ref": "#/components/schemas/JsonResponse"
                }
            },
            "text/plain": {
                "schema": {
                    "type": "string"
                }
            }
        },
        "description": "OK"
    },
    "204": {
        "content": {
            "application/hal+json": {
                "schema": {
                    "$ref": "#/components/schemas/EntityModelJsonResponse"
                }
            },
            "application/vnd.something": {},
            "text/plain": {
                "schema": {
                    "type": "string"
                }
            }
        },
        "description": "No Content"
    }
},

如果我在不更改代码的情况下重新启动服务器，则会生成以下响应

"operationId": "gettt_1",
"responses": {
    "200": {
        "content": {
            "application/hal+json": {
                "schema": {
                    "$ref": "#/components/schemas/EntityModelJsonResponse"
                }
            },
            "application/json": {
                "schema": {
                    "$ref": "#/components/schemas/JsonResponse"
                }
            },
            "text/plain": {
                "schema": {
                    "type": "string"
                }
            }
        },
        "description": "OK"
    },
    "204": {
        "content": {
            "application/vnd.something": {}
        },
        "description": "No Content"
    }
},

我希望重新启动我的服务器将始终生成相同的文档

Answer 1

你看过文档吗？

• https://springdoc.github.io/springdoc-openapi-demos/springdoc-properties.html#swagger-ui-properties

您可以使用 swagger-ui 属性，而不必重写标准排序方式（operationsSorter 和 tagsSorter）。

例如：

springdoc.swagger-ui.operationsSorter=method
springdoc.swagger-ui.tagsSorter=alpha

如果你想在服务器端下订单，你可以使用 OpenApiCustomiser，对元素进行排序

这是一个示例代码，您可以使用 Comparator 自定义，具体取决于您想要的排序逻辑：

例如，模式的字母顺序排序：

@Bean
public OpenApiCustomiser sortSchemasAlphabetically() {
    return openApi -> {
        Map<String, Schema> schemas = openApi.getComponents().getSchemas();
        openApi.getComponents().setSchemas(new TreeMap<>(schemas));
    };
}

标签排序示例，按字母顺序：

@Bean
public OpenApiCustomiser sortTagsAlphabetically() {
    return openApi -> openApi.setTags(openApi.getTags()
            .stream()
            .sorted(Comparator.comparing(tag -> StringUtils.stripAccents(tag.getName())))
            .collect(Collectors.toList()));
}

您可以完全控制元素顺序，并且可以根据您的用例对它们进行排序...

Answer 2

另一个标志mentioned here:

springdoc:
 writer-with-order-by-keys