Springdoc 隨機 api-docs 生成

Question

我希望生成一個采用不同內容類型的 api。

我面臨的問題是，如果我多次運行我的應用程序，我有不同的 output 文檔

@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

這里提到的另一個標志：

springdoc:
 writer-with-order-by-keys